Skip to main content
skill CX Codex

bug-reporting-excellence — Claude Code skill for bug reports

The bug-reporting-excellence skill guides an agent through clear bug reports with reproduction steps, environment details, and impact. Use it when documenting defects or setting reporting standards for a team.

MIT 1 installs ★ 533 updated 2026-10-25

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add proffesor-for-testing/agentic-qe --skill bug-reporting-excellence -a claude-code
Open on GitHub

What bug-reporting-excellence does

The skill provides a report structure covering the affected component, failure condition, severity, environment, expected and observed behavior, reproduction steps, and impact. It recommends attaching logs or screenshots, narrowing down the conditions, and keeping each defect in its own report.

A severity guide runs from Critical to Low, with examples of how impact maps to each level. Reproduction depends on precise environment details, including the OS and browser version; vague steps such as opening the app do not help. The skill also describes handing reports to subagents for triage, duplicate checks, and adding missing details.

What it helps with

  • draft a bug report with exact reproduction steps
  • separate expected behavior from observed behavior
  • rate severity based on the reported impact
  • split unrelated defects into separate reports
  • add environment details and supporting evidence

Example prompts for the agent

  • Write a report for this failure with the conditions, reproduction steps, expected behavior, and user impact.
  • Assess this defect’s severity and list the environment details needed to reproduce it.
  • Turn this description into separate reports if it contains more than one bug.

How to install bug-reporting-excellence

1Skills CLI (Vercel)

npx skills add proffesor-for-testing/agentic-qe --skill bug-reporting-excellence -a claude-code

2Manually: put the files in place

~/.claude/skills/bug-reporting-excellence/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/bug-reporting-excellence/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about bug-reporting-excellence

How do I install bug-reporting-excellence in Claude Code?

Run npx skills add proffesor-for-testing/agentic-qe --skill bug-reporting-excellence -a claude-code. The skill file is placed at ~/.claude/skills/bug-reporting-excellence/SKILL.md.

What does bug-reporting-excellence do?

It guides an agent in writing bug reports with reproduction conditions, expected and observed behavior, severity, and impact. It also covers environment details and keeping separate defects in separate reports.

What details help reproduce a bug?

Include precise steps and conditions, along with environment information such as the OS and browser version. The skill also recommends attaching logs or screenshots.

Source text

SKILL.md · MIT
---
name: bug-reporting-excellence
description: "Write high-quality bug reports that get fixed quickly. Use when reporting bugs, training teams on bug reporting, or establishing bug report standards."
category: quality-communication
priority: high
tokenEstimate: 900
agents: [qe-quality-analyzer, qe-production-intelligence, qe-flaky-test-hunter]
implementation_status: optimized
optimization_version: 1.0
last_optimized: 2025-12-03
dependencies: []
quick_reference_card: true
tags: [bugs, reporting, communication, triage, quality]
trust_tier: 2
validation:
  schema_path: schemas/output.json
  validator_path: scripts/validate-config.json
---

# Bug Reporting Excellence

<default_to_action>
When reporting bugs:
1. TITLE: `[Component] fails [Condition] causing [Impact]`
2. DESCRIBE: Expected behavior → Actual behavior → Steps to reproduce
3. INCLUDE: Environment, severity, screenshots/logs, business impact
4. ISOLATE: Narrow down conditions (browser, user, amount thresholds)
5. ONE BUG = ONE REPORT (don't combine issues)

**Bug Report Formula:**
```markdown
## [Component] Issue Title
**Severity:** Critical/High/Medium/Low
**Environment:** Production/Staging/Dev

### Expected Behavior
What should happen

### Actual Behavior
What actually happens (with error messages)

### Steps to Reproduce
1. Step one
2. Step two
3. Observe issue

### Impact
How this affects users/business
```

**Critical Success Factors:**
- Reproducible steps (100%)
- Environment info (100%)
- Business impact stated (90%)
- Screenshots or logs (80%)
</default_to_action>

## Quick Reference Card

### Severity Levels

| Level | Definition | Examples |
|-------|------------|----------|
| **Critical** | System down, data loss, security | DB deleted, payments broken, credentials exposed |
| **High** | Major feature broken, many users | Can't checkout, search broken, dashboard fails |
| **Medium** | Partial break, workaround exists | Filter broken (refresh works), slow export |
| **Low** | Cosmetic, rare edge case | Button wraps on mobile, tooltip wrong color |

### Title Formula
❌ Bad: "Checkout broken"
✅ Good: "Payment fails with Visa cards when order total > $1000"

**Pattern:** `[Component] fails [Condition] causing [Impact]`

---

## Essential Information

### Environment Details
```
Browser: Chrome 120.0.6099.109 (Windows)
OS: Windows 11 Pro
URL: https://example.com/checkout
Date/Time: 2025-10-17 14:23 UTC
User: [email protected] (ID: 12345)
Request ID: abc-123-def-456
```

### Supporting Evidence

**Error Messages:**
```json
{
  "error": "Payment service unavailable",
  "code": "GATEWAY_TIMEOUT",
  "requestId": "abc-123-def-456"
}
```

**Console Logs:**
```
[ERROR] PaymentGateway: Connection timeout after 30000ms
  at PaymentGateway.charge (gateway.js:145)
```

---

## Example: Excellent Bug Report

```markdown
## [Checkout] Payment processing times out for orders > $1000

**Severity:** High
**Environment:** Production
**Affected Users:** ~15% of premium purchases

### Expected Behavior
Payment completes within 5 seconds regardless of amount.

### Actual Behavior
For orders above $1000, payment gateway times out after 30 seconds.
User sees "Payment failed" error. Order not created.

### Steps to Reproduce
1. Add items totaling $1,050 to cart
2. Proceed to checkout
3. Enter payment: Visa 4532 1234 5678 9010
4. Click "Place Order"
5. Wait 30+ seconds
6. Observe timeout error

### Environment
- Browser: Chrome 120 (Windows 11)
- User: [email protected]
- Request ID: abc-123-def-456

### Evidence
Console error: `PaymentGateway timeout: 30000ms exceeded`
Network: /api/checkout: 30.14s (timeout)

### Impact
- Lost revenue: ~$15K/week from failed orders
- 23 support tickets this week
- Affects 15% of orders over $1000

### Additional Context
Started after Oct 15 deployment (v2.3.0)
Possibly related to PR #456 (fraud check)
```

---

## Anti-Patterns

| ❌ Bad | Problem | ✅ Good |
|--------|---------|--------|
| "Checkout is broken" | What doesn't work? | "Payment button doesn't respond when clicked" |
| "I saw an error" | No reproduction steps | Full steps with conditions |
| "Page loads slowly" | No specifics | "Dashboard takes 12s to load (should be <3s)" |
| Multiple bugs in one | Can't track separately | One report per bug |

---

## Agent Integration

```typescript
// Automated bug triage
const triage = await Task("Triage Bug", {
  title: 'Payment fails for orders > $1000',
  description: bugDescription,
  steps: reproductionSteps
}, "qe-quality-analyzer");

// Returns: { severity, priority, component, suggestedAssignee, relatedIssues }

// Duplicate detection
const dupeCheck = await Task("Check Duplicates", {
  bugReport: newBug,
  similarityThreshold: 0.85
}, "qe-quality-analyzer");

// Bug report enhancement
const enhanced = await Task("Enhance Report", {
  originalReport: userSubmittedBug,
  addMissingInfo: true,
  identifyRootCause: true
}, "qe-production-intelligence");
```

---

## Agent Coordination Hints

### Memory Namespace
```
aqe/bug-reports/
├── triaged/*          - Bug triage results
├── duplicates/*       - Duplicate detection
├── patterns/*         - Recurring bug patterns
└── root-cause/*       - Root cause analyses
```

### Fleet Coordination
```typescript
const bugFleet = await FleetManager.coordinate({
  strategy: 'bug-investigation',
  agents: [
    'qe-quality-analyzer',        // Triage and categorize
    'qe-flaky-test-hunter',       // Check if test-related
    'qe-production-intelligence'  // Check production logs
  ],
  topology: 'parallel'
});
```

---

## Related Skills
- [technical-writing](../technical-writing/) - Clear bug documentation
- [exploratory-testing-advanced](../exploratory-testing-advanced/) - Finding bugs
- [sherlock-review](../sherlock-review/) - Root cause investigation

---

## Remember

Your bug report is the starting point for someone else's work. Make it **complete** (all info needed), **clear** (anyone can follow), **concise** (no noise), and **actionable** (developer knows next step).

**Good bug reports = Faster fixes = Better product = Happier users**

## Skill Composition

- **After finding bug** → Start with `/test-failure-investigator` for root cause
- **Prevent regression** → Use `/regression-testing` to add test preventing recurrence
- **Track quality** → Feed into `/test-metrics-dashboard` for trend analysis

## Gotchas

- Agent omits environment details (OS, browser version, node version) — these are critical for reproduction
- "Steps to reproduce" that start with "1. Open the app" are useless — specify exact URL, user role, and state
- Agent combines multiple bugs into one report — enforce ONE BUG = ONE REPORT strictly
- Screenshots without annotations don't help — always highlight the actual error area
- Severity assessment is often wrong — agent marks everything as "critical" or everything as "low"

© proffesor-for-testing · MIT · proffesor-for-testing/agentic-qe

Similar skills

All skills for Testing and QA →

From the same set73

The whole set →
qcsd-cicd-swarm The qcsd-cicd-swarm Claude Code skill checks CI/CD pipelines before release and assesses deployment readiness. It reviews regression risk and flaky tests, then returns a RELEASE, REMEDIATE, or BLOCK decision. CX Codex +1 104installs test-idea-rewriting test-idea-rewriting is a Claude Code skill that turns passive test descriptions into active actions with observable results. It runs when test ideas are vague or fail quality validation. CX Codex +1 104installs cicd-pipeline-qe-orchestrator The cicd-pipeline-qe-orchestrator skill assigns quality checks and QE agents to CI/CD stages, from commit through production. Use it to plan pipeline testing and define release gates. CX Codex +1 1installs accessibility-testing accessibility-testing — a skill with checklists and test snippets for checking keyboard navigation, color contrast and screen reader support against WCAG 2.2. CX Codex +1 1installs qe-visual-accessibility qe-visual-accessibility runs WCAG 2.2 accessibility audits and catches UI regressions through pixel-diff screenshot comparisons. It validates responsive layouts after CSS or component changes. CX Codex +1 1installs exploratory-testing-advanced exploratory-testing-advanced is a Claude Code skill for planning exploratory sessions, investigating bugs, and recording defects. It supports checks of new features and issues automated tests miss. CX Codex +1 1installs compliance-testing compliance-testing is a skill that checks an app against GDPR, CCPA, HIPAA, SOC2, and PCI-DSS, and tests user rights, encryption, and access logs before audits or during work with personal data. CX Codex +1 1installs quality-metrics Tracks software quality metrics like defect density, DORA indicators, MTTD, and bug escape rates for CI quality gates. CX Codex +1 1installs

Project sponsors

Companies that keep this analytics open