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
npx skills add proffesor-for-testing/agentic-qe --skill bug-reporting-excellence -a claude-codeWhat 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-code2Manually: put the files in place
~/.claude/skills/bug-reporting-excellence/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/bug-reporting-excellence/
1Skills CLI (Vercel)
npx skills add proffesor-for-testing/agentic-qe --skill bug-reporting-excellence -a codex2Manually: put the files in place
.agents/skills/bug-reporting-excellence/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add proffesor-for-testing/agentic-qe --skill bug-reporting-excellence -a cursor2Manually: put the files in place
.cursor/skills/bug-reporting-excellence/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install proffesor-for-testing/agentic-qe assets/skills/bug-reporting-excellence2Manually: put the files in place
.github/skills/bug-reporting-excellence/SKILL.md1Skills CLI (Vercel)
npx skills add proffesor-for-testing/agentic-qe --skill bug-reporting-excellence -a gemini-cli2Platform CLI
gemini skills install https://github.com/proffesor-for-testing/agentic-qe --path assets/skills/bug-reporting-excellenceManually: put the files in place
.devin/skills/bug-reporting-excellence/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add proffesor-for-testing/agentic-qe --skill bug-reporting-excellence -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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