Bug Investigation
Purpose
Diagnose a defect and plan its fix without regressing behavior: reproduce it, find the true root cause, fix minimally, and pin it with a regression test. Produces a bug work item in ../../work-items/bugs/.
When to Use
- Request classified as bug, or a defect surfaced during other work.
- Not for new capability (
feature-planning) or restructuring (refactor-planning).
Inputs
- Symptom description, environment, affected area.
- Repo access; relevant logs/traces if available.
Discovery Questions
- What is the expected vs actual behavior?
- Exact steps, environment, and build (debug/release) where it occurs?
- Is it consistent or intermittent? Recent change that introduced it?
- Blast radius — who/what is affected, and how severe?
Responsibilities
- Audit the affected area.
- Reproduce reliably (or document why not, with evidence).
- Find the root cause — the actual mechanism, not the surface symptom.
- Plan a minimal, behavior-preserving fix (except for the defect).
- Add a regression test that fails before and passes after, specified as a Gherkin scenario stating the reproduction and the observable correct outcome (
testing/gherkin-specifications).
- Plan validation in the relevant build/environment.
Required Workflow
- Gather symptoms + environment.
- Reproduce (record the repro).
- Trace to root cause.
- Plan the minimal fix + regression test.
- Define validation steps.
- Record the bug work item (severity, repro, cause, fix, test).
Decision Rules
- No fix without a confirmed root cause (or an explicit, justified hypothesis if it can't be reproduced).
- Fix the cause; don't paper over the symptom.
- Every bug gets a regression test (
../../system/TESTING_SELECTION_RULES.md).
- If the "bug" is actually intended behavior, surface it — don't silently change behavior.
Rules
- Minimal change footprint; preserve unrelated behavior.
- Distinguish confirmed cause from hypothesis.
- Validate in the environment where the bug appears (e.g. release, not just debug).
Anti-Patterns
- Symptom-patching without root cause.
- Fixing without a regression test.
- Broad refactors bundled into a bug fix.
- Claiming "fixed" without reproducing/validating.
Validation Checklist
Definition of Done
A recorded bug work item with severity, reproduction, confirmed root cause, a minimal fix plan, a regression test, and validation steps — ready for implementation and verification.
Related Skills
existing-project-audit, task-planning, testing-strategy, code-review, security-review (if security-relevant), project-orchestrator.
Related Knowledge
../../knowledge/ (module behavior, prior incidents).
Related References
../../references/<topic>/ only if the failing area needs grounding.
Context Loading Guidance
- Requires: symptom, affected-area code, logs/traces if any.
- Does not require: the whole repo, unrelated references, unrelated skills.
- May load:
testing-strategy for the regression test; security-review if the bug is security-relevant.
- Stop when: cause, fix plan, and regression test are recorded.
Token Efficiency Guidance
Read only the failing path and its immediate collaborators. Capture the root cause succinctly; don't paste large traces — quote the decisive lines.
1---2name: bug-investigation3description: Use to diagnose and plan the fix for a defect — audit, reproduce, find root cause, fix minimally, add a regression test, and validate. Fixes the cause, not the symptom, and pins it so it can't return.4---56# Bug Investigation78## Purpose910Diagnose a defect and plan its fix without regressing behavior: reproduce it, find the true root cause, fix minimally, and pin it with a regression test. Produces a bug work item in `../../work-items/bugs/`.1112## When to Use1314- Request classified as **bug**, or a defect surfaced during other work.15- **Not** for new capability (`feature-planning`) or restructuring (`refactor-planning`).1617## Inputs1819- Symptom description, environment, affected area.20- Repo access; relevant logs/traces if available.2122## Discovery Questions2324- What is the expected vs actual behavior?25- Exact steps, environment, and build (debug/release) where it occurs?26- Is it consistent or intermittent? Recent change that introduced it?27- Blast radius — who/what is affected, and how severe?2829## Responsibilities3031- **Audit** the affected area.32- **Reproduce** reliably (or document why not, with evidence).33- Find the **root cause** — the actual mechanism, not the surface symptom.34- Plan a **minimal, behavior-preserving fix** (except for the defect).35- Add a **regression test** that fails before and passes after, specified as a Gherkin scenario stating the reproduction and the observable correct outcome (`testing/gherkin-specifications`).36- Plan **validation** in the relevant build/environment.3738## Required Workflow39401. Gather symptoms + environment.412. Reproduce (record the repro).423. Trace to root cause.434. Plan the minimal fix + regression test.445. Define validation steps.456. Record the bug work item (severity, repro, cause, fix, test).4647## Decision Rules4849- No fix without a confirmed root cause (or an explicit, justified hypothesis if it can't be reproduced).50- Fix the cause; don't paper over the symptom.51- Every bug gets a regression test (`../../system/TESTING_SELECTION_RULES.md`).52- If the "bug" is actually intended behavior, surface it — don't silently change behavior.5354## Rules5556- Minimal change footprint; preserve unrelated behavior.57- Distinguish confirmed cause from hypothesis.58- Validate in the environment where the bug appears (e.g. release, not just debug).5960## Anti-Patterns6162- Symptom-patching without root cause.63- Fixing without a regression test.64- Broad refactors bundled into a bug fix.65- Claiming "fixed" without reproducing/validating.6667## Validation Checklist6869- [ ] Symptom + environment captured.70- [ ] Reliable repro (or documented non-repro).71- [ ] Root cause identified (confirmed vs hypothesis noted).72- [ ] Minimal fix planned.73- [ ] Regression test defined.74- [ ] Validation steps defined.7576## Definition of Done7778A recorded bug work item with severity, reproduction, confirmed root cause, a minimal fix plan, a regression test, and validation steps — ready for implementation and verification.7980## Related Skills8182`existing-project-audit`, `task-planning`, `testing-strategy`, `code-review`, `security-review` (if security-relevant), `project-orchestrator`.8384## Related Knowledge8586`../../knowledge/` (module behavior, prior incidents).8788## Related References8990`../../references/<topic>/` only if the failing area needs grounding.9192## Context Loading Guidance9394- **Requires:** symptom, affected-area code, logs/traces if any.95- **Does not require:** the whole repo, unrelated references, unrelated skills.96- **May load:** `testing-strategy` for the regression test; `security-review` if the bug is security-relevant.97- **Stop when:** cause, fix plan, and regression test are recorded.9899## Token Efficiency Guidance100101Read only the failing path and its immediate collaborators. Capture the root cause succinctly; don't paste large traces — quote the decisive lines.
ahtishamshahzad