| name | bug-investigation |
| description | Use for defects, regressions, outages, flaky tests, and unexpected behavior. Guides the agent through triage, containment, reproduction, hypotheses, root-cause evidence, fix verification, and recurrence prevention. Do not use as the primary workflow for new features; use double-diamond-feature instead. |
Bug Investigation
Trigger Signals
Use this skill when the user reports:
- broken behavior
- a regression
- a failing or flaky test
- production degradation
- incorrect data/output
- an incident-like symptom
- a bug report with expected vs actual behavior
Do not use as the primary workflow for new features. Use double-diamond-feature instead.
Workflow
1. Triage
Classify:
- severity: low, medium, high, incident
- user/system impact
- data risk
- production risk
- containment needed or not
If harm is ongoing, contain first and preserve evidence.
2. Problem Report
Capture:
- expected behavior
- actual behavior
- reproduction steps or evidence gap
- environment/version/time window
- relevant logs/traces/screenshots if available
3. Evidence Inspection
Inspect relevant code, tests, recent changes, config, logs, and runtime artifacts. Reuse Harness Forge surfaces when present: .hforge/runtime/repo/repo-map.json, .hforge/runtime/findings/risk-signals.json. Label assumptions clearly.
4. Hypotheses
Create a ranked hypothesis table:
| ID | Hypothesis | Likelihood | Evidence for | Evidence against | Test | Status |
|---|
Prefer tests that rule out multiple causes. Record negative results.
5. Fix
Implement the smallest fix for the confirmed cause. Avoid broad refactors unless the cause requires them.
6. Verify
Verify using:
- reproduction now passes
- regression test added or updated
- relevant existing tests
- manual verification if automated tests are unavailable
7. Prevent Recurrence
Recommend one or more:
- regression test
- input validation
- type/schema guard
- monitor/alert
- docs/playbook update
- postmortem or A3/8D-lite for severe/recurrent issues
Output Before Fix
## Bug Investigation Frame
### Triage
- Severity:
- Impact:
- Data risk:
- Containment:
### Problem report
- Expected:
- Actual:
- Reproduction:
- Environment:
### Evidence
- User-provided:
- Repository/runtime:
- Assumptions:
### Hypotheses
| ID | Hypothesis | Likelihood | Evidence for | Evidence against | Test | Status |
|---|---|---|---|---|---|---|
### Fix plan
- Confirmed/likely cause:
- Proposed fix:
- Verification:
- Prevention:
Output After Fix
## Bug Fix Report
- Root cause evidence:
- Changes made:
- Verification:
- Regression coverage:
- Recurrence prevention:
- Follow-up/postmortem need:
Root-Cause Honesty
Do not claim a root cause unless it is supported by reproduction, logs, tests, code-path evidence, or clearly stated confidence.
Target Compatibility
This skill is plain-markdown and host-agnostic. Claude Code invokes it as /bug-investigation; Codex selects it via /skills or $bug-investigation. Do not rely on host-native hooks or interactive prompts.
