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 at ../../work-items/bugs/BUG-<NNN>.md. Intake (duplicate check, ID, priority, week, ledger) is owned by project-management; this skill owns the diagnosis.
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; confirm the bug has its
BUG-NNN record and is not a duplicate (project-management intake).
- State the expected behavior: find the existing scenarios for the area (
features/); if none covers it, write one (../../system/GHERKIN_RULES.md).
- Reproduce (record the repro) and compare expected vs actual. Write the regression scenario — it must fail on the current code.
- Trace to root cause — the fix must explain why the scenario failed.
- Plan the minimal fix + the regression test that implements the scenario; the scenario stays in
features/ permanently, tagged @regression @bug-NNN.
- Define validation steps, including the regression suite.
- Record the bug work item (P0–P3 priority, repro, cause, fix, test) and hand back to
project-management to schedule the fix task and update the ledger.
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.
- Fix with the existing technology. An upgrade belongs in a bug fix only when the dependency itself is the root cause (
../../system/TECHNOLOGY_GOVERNANCE_RULES.md §3).
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, project-management (intake, scheduling, ledger).
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.4metadata:5 source: https://skillmd.com/skills/ahtishamshahzad/bug-investigation6---78# Bug Investigation910## Purpose1112Diagnose 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 at `../../work-items/bugs/BUG-<NNN>.md`. Intake (duplicate check, ID, priority, week, ledger) is owned by `project-management`; this skill owns the diagnosis.1314## When to Use1516- Request classified as **bug**, or a defect surfaced during other work.17- **Not** for new capability (`feature-planning`) or restructuring (`refactor-planning`).1819## Inputs2021- Symptom description, environment, affected area.22- Repo access; relevant logs/traces if available.2324## Discovery Questions2526- What is the expected vs actual behavior?27- Exact steps, environment, and build (debug/release) where it occurs?28- Is it consistent or intermittent? Recent change that introduced it?29- Blast radius — who/what is affected, and how severe?3031## Responsibilities3233- **Audit** the affected area.34- **Reproduce** reliably (or document why not, with evidence).35- Find the **root cause** — the actual mechanism, not the surface symptom.36- Plan a **minimal, behavior-preserving fix** (except for the defect).37- 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`).38- Plan **validation** in the relevant build/environment.3940## Required Workflow41421. Gather symptoms + environment; confirm the bug has its `BUG-NNN` record and is not a duplicate (`project-management` intake).432. State the expected behavior: find the existing scenarios for the area (`features/`); if none covers it, write one (`../../system/GHERKIN_RULES.md`).443. Reproduce (record the repro) and compare expected vs actual. Write the **regression scenario** — it must fail on the current code.454. Trace to root cause — the fix must explain why the scenario failed.465. Plan the minimal fix + the regression test that implements the scenario; the scenario stays in `features/` permanently, tagged `@regression @bug-NNN`.476. Define validation steps, including the regression suite.487. Record the bug work item (P0–P3 priority, repro, cause, fix, test) and hand back to `project-management` to schedule the fix task and update the ledger.4950## Decision Rules5152- No fix without a confirmed root cause (or an explicit, justified hypothesis if it can't be reproduced).53- Fix the cause; don't paper over the symptom.54- Every bug gets a regression test (`../../system/TESTING_SELECTION_RULES.md`).55- If the "bug" is actually intended behavior, surface it — don't silently change behavior.56- Fix with the existing technology. An upgrade belongs in a bug fix only when the dependency itself is the root cause (`../../system/TECHNOLOGY_GOVERNANCE_RULES.md` §3).5758## Rules5960- Minimal change footprint; preserve unrelated behavior.61- Distinguish confirmed cause from hypothesis.62- Validate in the environment where the bug appears (e.g. release, not just debug).6364## Anti-Patterns6566- Symptom-patching without root cause.67- Fixing without a regression test.68- Broad refactors bundled into a bug fix.69- Claiming "fixed" without reproducing/validating.7071## Validation Checklist7273- [ ] Symptom + environment captured.74- [ ] Reliable repro (or documented non-repro).75- [ ] Root cause identified (confirmed vs hypothesis noted).76- [ ] Minimal fix planned.77- [ ] Regression test defined.78- [ ] Validation steps defined.7980## Definition of Done8182A 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.8384## Related Skills8586`existing-project-audit`, `task-planning`, `testing-strategy`, `code-review`, `security-review` (if security-relevant), `project-orchestrator`, `project-management` (intake, scheduling, ledger).8788## Related Knowledge8990`../../knowledge/` (module behavior, prior incidents).9192## Related References9394`../../references/<topic>/` only if the failing area needs grounding.9596## Context Loading Guidance9798- **Requires:** symptom, affected-area code, logs/traces if any.99- **Does not require:** the whole repo, unrelated references, unrelated skills.100- **May load:** `testing-strategy` for the regression test; `security-review` if the bug is security-relevant.101- **Stop when:** cause, fix plan, and regression test are recorded.102103## Token Efficiency Guidance104105Read only the failing path and its immediate collaborators. Capture the root cause succinctly; don't paste large traces — quote the decisive lines.