# Bug Investigation

> 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.

- Skill: `ahtishamshahzad/bug-investigation` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ahtishamshahzad/bug-investigation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ahtishamshahzad/bug-investigation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: ahtishamshahzad (https://skillmd.com/u/ahtishamshahzad)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ahtishamshahzad/bug-investigation

---


# 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

1. Gather symptoms + environment.
2. Reproduce (record the repro).
3. Trace to root cause.
4. Plan the minimal fix + regression test.
5. Define validation steps.
6. 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

- [ ] Symptom + environment captured.
- [ ] Reliable repro (or documented non-repro).
- [ ] Root cause identified (confirmed vs hypothesis noted).
- [ ] Minimal fix planned.
- [ ] Regression test defined.
- [ ] Validation steps defined.

## 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.