diagnose-bug

Files (3)

• SKILL.md
• report-template.md · references/
• verification-playbook.md · references/

SKILL.md (first lines)

# diagnose-bug

Find the root cause of a bug, prove it, and hand over a report that another agent or
developer can act on without redoing the investigation.

## Contract

- **Input:** a bug description in any form — issue text, chat message, stack trace, log excerpt,
  failing test, or "it's broken".
- **Output:** one Markdown report at `docs/bugs/YYYY-MM-DD-<slug>.md` (template in
  `references/report-template.md`) plus a short summary in the conversation.
- **Not in scope:** implementing the fix. The report ends with proposals and a recommendation;
  the user chooses. Never commit. Leave the working tree as you found it, except for the
  reproduction test (see Phase 6).
- **Self-contained report:** a reader with only the report must be able to continue — reproduce
  the bug, see which causes were excluded and why, follow the causal chain to the root, and pick
  a fix. Dead ends are part of the deliverable, because they are exactly what the next person
  would otherwise repeat.

**Explicit invocation.** This skill starts only when it was named — `/diagnose-bug`,
`/cc-ai-dev:diagnose-bug`, the name in the prompt, or a hand-off from another skill such as
`auto-loop`. A request that merely describes a bug ("why does this fail", a pasted stack trace)
is handled as an ordinary request without this workflow.

## Principles

**1. The symptom is where the bug becomes visible, not where it lives.** A null dereference in a
formatter is a symptom; the parser that swallowed an exception two calls earlier is the cause.
Fixing the symptom leaves the class of failure open and adds a null check that hides the next
one. Use this stop criterion to decide how deep to go: *the root cause is the deepest cause that
lies within this project's control and whose correction prevents the whole class of failure, not
just this instance.* Deeper ("the language allows null") yields nothing actionable; shallower
fixes one case.

**2. Every claim is a hypothesis until verified.** This includes the bug report itself: the
reporter's "expected behavior" may be wrong, the "obvious" cause in the stack trace is often not
the cause, and what you remember about a library may not match the installed version. Keep an
**evidence ledger** (below) from the first minute. A claim enters the ledger as OPEN and becomes
VERIFIED or REFUTED only with a method and concrete evidence attached. Verify through three
sources, in this order of strength:

1. **Experiments** — a test, a script, a command whose outcome the hypothesis predicts.
2. **Code in this repository** — read the actual call path, config, and data flow; cite `file:line`.
3. **Frameworks and libraries** — the installed version (lockfile, project file), then its source
   in the dependency cache or its changelog for that exact version. Never cite library behavior
   from memory alone. See `references/verification-playbook.md`.

**3. Prediction is the strongest evidence.** A hypothesis is confirmed when it predicts something
you have not yet observed, and the prediction holds — typically: "if this is the cause, then
this minimal temporary change makes the reproduction pass". Observing that a hypothesis is
*consistent* with the symptom is weak; every plausible hypothesis is consistent with it.

**4. Offer choices, then recommend.** Different fixes trade speed, risk, and robustness
differently, and the user knows constraints you do not (release schedule, ownership, API
consumers). Present at least two proposals with honest trade-offs, then name the one you would
pick and why. A menu without a recommendation just moves the work to the reader.

## Evidence ledger

Maintain this table throughout and put it in the report verbatim:

| # | Claim | Status | Method | Evidence |
|---|-------|--------|--------|----------|
| 1 | Bug reproduces on `main` at `a1b2c3d` | VERIFIED | Ran new test `tests/test_x.py::test_repro` | Fails with `AssertionError: expected 3, got 4` |
| 2 | `sort()` comparator returns boolean | VERIFIED | Read `src/report.ts:41` | `.sort((a, b) => a.date > b.date)` |
| 3 | Reporter's expected value 3 is correct | OPEN | — | Spec not found; asked user |

Status values: `OPEN`, `VERIFIED`, `REFUTED`. If the final diagnosis rests on an OPEN claim, the
report status cannot be CONFIRMED (see Phase 6). Mark claims that came from the user or from an
assumption you had to make with their origin in the Method column, e.g. `assumed (non-interactive)`.

## Workflow

Work through the phases in order. Each phase names what must be true before the next starts.

### Phase 0 — Intake

Capture what is known and what is claimed. From the bug report and the repository, establish:

- Observed behavior (exact message, output, or effect) and expected behavior — with the source of
  the expectation (spec, test, docs, reporter's opinion).
- Where it happens: environment, version or commit, configuration, data, frequency
  (always / intermittent / once).
- Since when, if known, and what changed around that time.
- Stack, runtime, test framework, and how tests are run in this repository.

Everything the reporter states goes into the ledger as OPEN. If information needed for
reproduction is missing, ask — see "Interactive vs. non-interactive". Do not start theorizing
about causes yet; a theory formed before reproduction anchors the rest of the investigation.

*Gate:* you can state observed vs. expected behavior in one sentence each, and you know how to
run this project's tests.

### Phase 1 — Reproduce

Get a reliable reproduction before anything else. In order of preference:

1. A failing automated test in the project's own test framework, as narrow as possible.
2. A script or command sequence with deterministic output.
3. A documented manual sequence, if the above are impossible (UI-only, external system).

For intermittent bugs, find what makes it deterministic (fixed seed, forced timing, repeated
runs with a count) — an intermittent reproduction is still a reproduction if you can state the
rate. Record the exact command and its output in the report.

If you cannot reproduce: record every attempt and its outcome, ask the user for the missing
piece (data, environment, steps), and if that is not possible, continue with static analysis but
mark every downstream claim OPEN. The report status will be at best PROBABLE.

*Gate:* a command that fails now and is expected to pass once the bug is fixed.

### Phase 2 — Gather evidence and form hypotheses

Collect evidence *before* choosing a favorite cause:

- Read the full call path from entry point to the failure, not just the frame in the stack trace.
- Check history: `git log -S`/`-G` for the involved identifiers, `git blame` on the failing lines,
  `git bisect` when a known-good commit exists. "Since when" often points straight at the cause.
- Check inputs, configuration, and data that the path depends on; compare the failing case with a

From CreativeCodersTeam/ai-store, Apache-2.0.

More from CreativeCodersTeam/ai-store