| name | bug-report |
| description | Author a structured bug report from a description, OR analyze code/logs to derive likely bugs. Captures reproduction steps, severity, device matrix, expected vs actual, and attachments. Use after a manual QA failure or when the user describes a defect. |
| argument-hint | [--from-description | --from-code=<path> | --from-crashlog=<path>] |
| user-invocable | true |
| allowed-tools | Read, Glob, Grep, Write, Edit, Bash, AskUserQuestion |
| model | sonnet |
Bug Report
Turn a vague observation into a fileable, actionable defect record. Three
input modes — user description, target code/files, or a crash log.
Phase 1: Pick the Mode
If --from-description (or no flag): collect details from the user via
AskUserQuestion.
If --from-code=<path>: read the specified file(s) and look for likely
bugs (unsafe optionals, race conditions, leaked subscriptions, etc.).
If --from-crashlog=<path>: read the crash log, identify the failing
stack frame, and reverse-engineer steps.
Phase 2A: From User Description
Walk through these prompts via AskUserQuestion in order:
- Title — one line, action + outcome ("Sign-in fails after biometric
prompt cancel").
- Severity — S1 (crash, data loss, blocks release), S2 (major
feature broken, no workaround), S3 (minor feature broken, workaround
exists), S4 (cosmetic).
- Affected platforms — iOS / Android / both.
- Device(s) reproduced on — model + OS version. List all confirmed.
- Build version + commit SHA — the build under which the bug was
seen.
- Reproduction steps — numbered, unambiguous. Each step should be
verifiable on a fresh install.
- Expected result.
- Actual result.
- Frequency — every time / often (>50%) / sometimes / once.
- Attachments — screenshots, screen recordings, crash logs, charles
captures, video file paths.
- Workaround — if any.
Keep collected answers in working memory and assemble them in Phase 4.
Phase 2B: From Code
Read the target file(s). Check for these patterns:
- Force-unwrapped optionals on user input.
- Unchecked array index access.
- Async work without cancellation that captures view state.
- Missing offline / error / loading branches.
- Non-idempotent network mutations (no idempotency key).
- Missing feature-flag fallbacks.
- Leaked subscriptions / observers (RN useEffect missing cleanup,
Combine cancellables not stored, Flutter StreamSubscription not
cancelled, Android Job not cancelled).
- Hardcoded keys, URLs, or environment names.
- Race conditions in
Promise.all ordering.
- Memory: closures capturing strong
self in iOS, missing [weak self].
- Deep links accepting unsanitized parameters.
For each finding, propose a bug report with synthesized reproduction.
Phase 2C: From Crash Log
Read the crash log. Extract:
- Crash type (NSException, SIGSEGV, fatal Dart error, ANR, OutOfMemory).
- Top frame in the app's own code.
- The thread (main vs background).
- The OS version, device, build.
- The date and time.
Search the codebase for the failing symbol or file. Read the surrounding
code. Hypothesize the trigger condition. Propose reproduction steps.
If the log lacks an app-level frame (pure framework crash), surface that
and suggest enabling symbolication.
Phase 3: Triage
For every assembled report, derive:
- Severity — apply S1-S4 rules. Confirm with the user if ambiguous.
- Frequency — affects priority.
- Priority — derived from severity + frequency + business impact:
P0 (drop everything), P1 (current sprint), P2 (next sprint), P3
(backlog).
Surface the proposed severity/priority via AskUserQuestion and let the
user override.
Phase 4: Render the Report
Use this template:
# BUG-[NNN]: [Title]
**Filed**: [date] by [author]
**Severity**: S[1-4]
**Priority**: P[0-3]
**Status**: Open
**Affected platforms**: iOS / Android / both
**Affected build**: [version + commit]
**Frequency**: [every time / often / sometimes / once]
## Devices Reproduced
- [Model + OS]
- [Model + OS]
## Reproduction Steps
1. ...
2. ...
## Expected
[what should happen]
## Actual
[what happens instead]
## Workaround
[if any]
## Attachments
- [path or link]
## Suspected Area
[code path, module, recent commit, related ADR/PRD]
## Related
- Story: [path or ID]
- ADR: [ID]
- PRD: [path]
- Similar bugs: [list]
## Notes
[free text — investigation log starts here]
Number the bug as the next available BUG-NNN by globbing
production/qa/bugs/BUG-*.md.
Slug naming: BUG-NNN-[short-kebab-slug].md.
Phase 5: Save
Ask: "May I write this to production/qa/bugs/BUG-[NNN]-[slug].md?"
On approval, write the file. Append to
production/session-state/active.md:
## Bug Filed — [date]
- ID: BUG-NNN
- Title: [title]
- Severity / Priority: S[N] / P[N]
- Path: production/qa/bugs/BUG-[NNN]-[slug].md
- Next: /bug-triage to schedule, or hand to engineer
Phase 6: Cross-Link
If the bug is suspected to break a regression test target, propose:
"Add this bug to the regression suite via /regression-suite --add-bug=BUG-NNN."
If the bug stems from a story that recently closed, propose linking it in
that story's Closing Notes.
If a hotfix is warranted, propose /hotfix BUG-NNN.
Quality Gates / PASS-FAIL
A bug report passes if it has:
- A non-empty title that describes outcome, not feeling.
- Reproduction steps that another engineer can follow on a fresh build.
- Expected vs actual cleanly separated.
- A severity AND priority assigned.
- A device list with at least one entry.
- A build version + commit SHA OR a clear note "build version unknown".
Reject and re-prompt for any missing field.
Examples
Example 1 — User description:
Tester reports "the sign-in screen sometimes hangs". Skill walks through
every prompt, derives S2/P1, writes BUG-067 with 5-step repro, lists
iPhone 13 + iOS 17.5 + iPhone SE + iOS 16.7.
Example 2 — From crash log:
User pastes a .crash path. Skill extracts the top frame
(PaymentReducer.applyPromo), reads that file, sees an unguarded
force-unwrap on a server response field, drafts BUG-068 with
hypothesized repro: "Apply promo code with empty discount payload".
Next Steps
- High-severity bug ->
/hotfix BUG-NNN to launch the emergency flow.
- Otherwise ->
/bug-triage at sprint start to schedule.
- For S1/S2 closes ->
/regression-suite --add-bug=BUG-NNN.
