| name | report-bug |
| description | Creates structured bug report documents with reproduction steps, expected vs actual behavior, and severity classification. Use when the user asks to "report a bug", "file a bug", "document a defect", "log an issue", or mentions a bug, defect, regression, or unexpected behavior that needs to be tracked.
|
Bug Report
Instructions
Create a bug report document for $ARGUMENTS in docs/bugs/. $ARGUMENTS is a description
of the bug, a reference to a use case (UC-XXX) or technical task (TT-XXX) where
the bug was discovered, or a full GitHub issue URL.
Origin Detection
Determine the origin of the bug report from $ARGUMENTS:
github-issue — $ARGUMENTS contains a GitHub issue URL (e.g., https://github.com/owner/repo/issues/42). The issue already exists and is the source of truth.human-in-the-loop — $ARGUMENTS is a description or artifact reference with no issue URL. The bug report document becomes the source of truth and a new GitHub issue will be created.
DO NOT
- Write vague reproduction steps that cannot be followed independently
- Guess the root cause unless evidence is clear — state what is observed, not what is assumed
- Combine multiple unrelated bugs in one report
- Downplay severity — classify based on actual user or system impact
- Skip searching for related bugs — check
docs/bugs/ for duplicates first
Nexa Rules Gate
Read and follow ${CLAUDE_PLUGIN_ROOT}/shared/readiness/NEXA_RULES_GATE.md.
Template
Use templates/bug-report.md as the document structure.
Example Bug Report
Bug Report: Order total ignores discount codes
Overview
| |
|---|
| Bug ID | BUG-003 |
| Title | Order total ignores discount codes |
| Severity | High |
| Status | Open |
| Discovered In | UC-012 (Place Order) |
| Reported By | Evaluation of UC-012 |
| Origin | human-in-the-loop |
| GitHub Issue | https://github.com/acme/store/issues/47 |
Description
When a valid discount code is applied to an order, the order summary displays the
discounted line items correctly, but the final total is calculated from the original
(undiscounted) prices. The user is charged more than expected.
Steps to Reproduce
- Log in as a customer with an active account
- Add any item to the cart
- Navigate to checkout
- Enter discount code
SAVE20 (a valid 20% discount)
- Observe the line item prices (correctly discounted)
- Observe the order total
Expected Behavior
The order total equals the sum of the discounted line item prices plus tax and shipping.
Actual Behavior
The order total equals the sum of the original (undiscounted) line item prices plus tax
and shipping. The discount is visually applied to line items but not reflected in the total.
Environment
- Browser: Chrome 125
- OS: macOS 14.5
- Application version: commit
a1b2c3d
Related Artifacts
- Use Case: UC-012 (Place Order)
- Business Rule: BR-007 (Discount Application)
- Affected Files:
src/services/order-service.ts, src/components/checkout/OrderSummary.tsx
Workflow
- Check
docs/bugs/ for existing bug reports to determine the next BUG-XXX ID and avoid duplicates
- If origin is
github-issue:
a. Read the issue body using gh issue view <issue-number> --json title,body,labels
b. Extract the bug description, reproduction steps, and any context from the issue
c. Set the Origin field to the full GitHub issue URL
d. Set the GitHub Issue field to the same URL — do NOT create a new issue
- If origin is
human-in-the-loop:
a. Reproduce the bug or gather evidence from the user's description, logs, or test output
b. Set the Origin field to human-in-the-loop
- Write clear, numbered reproduction steps that another developer can follow
- Document expected vs actual behavior precisely
- Classify severity based on impact:
- Critical — System crash, data loss, security vulnerability, or complete feature failure
- High — Major feature broken, no workaround, affects many users
- Medium — Feature partially broken, workaround exists, or affects limited users
- Low — Cosmetic issue, minor inconvenience, or edge case
- Identify related artifacts (use cases, business rules, affected files)
- Set status to Open
- If origin is
human-in-the-loop:
a. Create a GitHub tracking issue by following the Before Implementation steps in ${CLAUDE_PLUGIN_ROOT}/shared/tracking/TRACKING.md
b. Update the bug report's GitHub Issue field with the issue URL
- If origin is
github-issue:
a. Follow the Before Implementation steps in ${CLAUDE_PLUGIN_ROOT}/shared/tracking/TRACKING.md — the issue already exists, so only ensure the bug .md and the issue link to each other (no new issue is created)
