Bug Investigation Skill

Take a bug report, follow it to the exact line(s) where the wrong behavior originates, apply the smallest correct fix, and record the result in a report file (default BUG_INVESTIGATION.md at the project root).

Gather context first

This skill ships standalone, so it can't assume your project's conventions, house style, or preferences the way it could for its author. Before doing the main work:

1. Auto-detect what you safely can from the repo — language/stack, base branch, build/test commands, existing config and docs. Never ask for something you can read for yourself.
2. Ask, don't assume, for the rest. Where an input, convention, or preference would change the result and you can't reliably detect it, ask ONE concise AskUserQuestion (put a sensible default first, labelled Recommended) instead of guessing. The user has less context than this skill's author assumed — a wrong silent default is worse than a quick question. Don't ask about things you can detect, and don't ask more than you need.

For this skill, confirm up front (only the items you can't already detect):

• What "wrong" means here — the expected-vs-actual behavior and any repro steps, if the report doesn't already make them concrete. Infer the affected feature area from the codebase where you can; only ask when the symptom is too vague to trace safely.
• Fix in place, or diagnose only — whether to apply the smallest correct fix with Edit (Recommended), or stop at a documented root-cause diagnosis with a proposed fix for the user to apply.
• Where the finding goes — BUG_INVESTIGATION.md at the project root (Recommended), a different path, or reported inline in chat with no file written.
• Severity & impact convention — the built-in MUST FIX / SHOULD FIX / FOLLOW-UP labels with a 1–10 impact score (Recommended), unless your repo already uses a different scale worth matching.

Subagents & parallelism (opt-in)

By default this skill runs inline in a single context — no subagent fan-out — to keep it cheap to run. Mapping the feature area with Grep/Glob/Read in this context handles the large majority of bugs.

Parallel subagents can be faster on large jobs (sprawling feature areas, many files, deep multi-pass tracing). Before spawning any subagent, stop and ask the user, for example:

This bug touches a wide area ([N files / several subsystems]). I can map and trace it inline here (cheaper, slower) or fan out [M] parallel subagents to explore in parallel (faster, more tokens). Which do you want?

Spawn subagents only after an explicit yes. If the user declines or doesn't answer, do the whole investigation inline.

Reading the report

Pull these out of $ARGUMENTS:

• Symptom — the observable wrong behavior (e.g. "a record from one account shows up under another account").
• Feature area — the surface that misbehaves (e.g. a list view, a checkout step, a search box).
• Repro steps — capture them verbatim if the user gave any.

When the report is thin, infer the feature area from the keywords in it and keep going rather than stalling. But if the expected-vs-actual behavior is genuinely ambiguous — vague enough that you'd be guessing which behavior is the bug — ask one concise question (see Gather context first) rather than tracing the wrong thing.

Investigation process

Step 1 — Map the feature

Locate every piece of code tied to the affected surface:

• Components, pages, and modules whose names match the feature.
• State containers (store slices, contexts, caches) that hold the relevant data.
• Network calls that read or write that data.
• The types and interfaces that flow through it.

Reach for Grep and Glob first — they cover most cases inline. For a feature spread across many unfamiliar files, broader exploration may help; if the user opted into subagents (see Subagents & parallelism), dispatch an exploration agent for the wide mapping, otherwise walk the files sequentially in this context.

Step 2 — Trace the data flow

Follow the value from where it enters to where the user sees it:

1. Source — the API/query response: how is it shaped or transformed on the way in?
2. State — where it lands: how is it written, and when (if ever) is it reset?
3. Render — the component: how does it read and display the value?

Watch specifically for (the examples below lean toward JS/TS frontends — first detect the actual stack from the repo and map each pattern to its equivalent in that language/framework):

• State that is never reset when the user switches account/context/record.
• State that is appended to when it should be replaced.
• State written from a stale closure — a value captured at the wrong moment.
• Race conditions — two async paths writing the same slot.
• Missing guards — a null/undefined read that quietly falls through to the wrong value.
• Shared state bleeding across sessions, tabs, or users.

Step 3 — Pin the root cause

Name the precise file(s) and line(s) where the behavior first goes wrong. Hold the suspect code up against a correct path elsewhere in the same codebase — the contrast usually confirms or kills the hypothesis.

Frequent culprits worth checking directly:

• setState([...existing, ...incoming]) where it should be setState(incoming) — an accumulation bug.
• A missing reset (clear/set(null)/set([])) on navigation or context change.
• An effect dependency array missing a key value, so stale data keeps rendering.
• A response consumed before it resolves, or two concurrent fetches racing.
• A component reading state[0] after the collection has been polluted with earlier entries.

Step 4 — Fix

If the user wants the fix applied (the default, confirmed under Gather context first), apply the minimal change to the source with Edit. Touch only the root cause — leave the surrounding code alone rather than refactoring around the bug. If they chose diagnose-only, skip the edit and carry the proposed fix into the report instead.

Step 5 — Write the report

Record the finding at the confirmed destination (default: create or append to BUG_INVESTIGATION.md in the project root; or a path the user named, or inline in chat), using the format below. Do this every time, even for a one-line fix.

Output format

# Bug — <short symptom title> (`<feature area>`)

**Date:** YYYY-MM-DD
**Feature area:** <component / feature name>
**Files fixed:** <list>
**Status:** FIXED | NEEDS_BACKEND_FIX | CANNOT_REPRODUCE | FURTHER_INVESTIGATION_NEEDED

---

## Issues

### [SEVERITY] 1. <Short title>

**File:** `path/to/file.ts:LINE_START–LINE_END`
**Impact score:** X/10
**Reason:** <what is wrong and why it matters>

**Current code:**
```lang
// the problematic code

Fix:

// the corrected code

Summary Table

## Rules

- **Read the file before editing** — confirm the exact lines and the surrounding context first.
- **Fix the cause, not the symptom** — no workaround patches layered on top of broken logic.
- **Check a known-good path** in the same codebase before declaring the fix correct.
- **Always record the finding** at the confirmed destination — never skip it, even for trivial fixes.
- If a report file already exists at that destination, **append** beneath the existing content — never overwrite.
- If the bug can't be reproduced or needs backend changes, document what you found and set the status to match.
- **Severity labels** (use exactly these):
  - `MUST FIX` — bug, data loss, security, broken behavior.
  - `SHOULD FIX` — correctness concern, UX regression, missing guard.
  - `FOLLOW-UP` — dead code, style, leftover debug logging.
- **Impact score** — rate 1–10:
  - 9–10: data loss, security, crashes.
  - 7–8: incorrect behavior visible to users.
  - 5–6: degraded UX, stale data, performance.
  - 3–4: maintainability, dead code, naming.
  - 1–2: style, whitespace, minor inconsistency.
- **Status rules:**
  - Any `MUST FIX` resolved → `FIXED`.
  - Root cause lives in the backend → `NEEDS_BACKEND_FIX`.
  - Not reproducible in the current code → `CANNOT_REPRODUCE`.
  - Partially understood, needs more digging → `FURTHER_INVESTIGATION_NEEDED`.