systematic-debugging

name	systematic-debugging
description	Systematic debugging — reproduce, trace, hypothesize, verify. This skill should be used when the user says 'debug this', 'why is this failing', 'trace the error', 'find the root cause', or encounters a bug, test failure, or unexpected behavior that needs methodical investigation.
user-invocable	true
args	[{"name":"issue","description":"Description of the bug or failing test (optional)","required":false}]

Scope

This skill owns the trace → hypothesize middle of root-cause investigation. It is invoked at T-2 of the bugfix task plan (tasks.yaml), after the bug is reproducible (T-1) and before the root cause is written to diagnosis.md (T-3, owned by config/steps/diagnose.yaml).

It does not reproduce the bug (T-1's job) and does not author the diagnosis document (T-3's job). It produces the evidence chain those steps depend on.

Premise: a reliable reproduction already exists. If it does not, stop and report that T-1 is incomplete — do not guess at causes from a flaky repro.

Execution

Parse $ARGUMENTS for the bug description, failing test, or symptom. Then run the four phases in order. Do not skip ahead — a fix proposed before Phase 3 is complete is a guess.

Phase 1 — Reproduce (confirm, don't perform)

Confirm the reproduction from T-1 triggers reliably in this session. Capture the exact command and its observed-vs-expected output. If it does not reproduce, stop here and report — there is nothing to trace.

Phase 2 — Trace

Follow the data and control flow from symptom backward toward origin. Gather evidence at each hop; do not theorize yet.

• Start at the observable failure (stack trace, assertion, wrong output) and walk upstream through callers, not downstream from a suspected cause.
• At each step record the actual value/state vs the expected one, with a concrete file:line reference.
• Inspect the boundary where actual first diverges from expected. That boundary, not the crash site, is where the root cause lives.
• Prefer evidence (logs, prints, a debugger, a narrowed test) over reasoning about what the code "should" do.

Phase 3 — Hypothesize

Form one falsifiable hypothesis of the root cause: a specific file:line plus why that code produces the observed divergence. State what you would expect to change if the hypothesis were true.

If more than one cause is plausible, rank them and test the cheapest-to-falsify first. A hypothesis you cannot state as a testable prediction is not yet a hypothesis — return to Phase 2.

Phase 4 — Verify

Prove the hypothesis before proposing any fix:

• Make the smallest possible intervention that the hypothesis predicts will change behavior, and confirm it does (and that reverting it restores the bug).
• Confirm the cause explains all observed symptoms, not just the loudest one.
• Distinguish root cause from symptom: if the "cause" is itself caused by something upstream, keep tracing.

Output

Present to the user (and, in a bugfix workflow, hand to T-3 for diagnosis.md):

• Symptom — the observable failure, from the reproduction.
• Root cause — file:line and why that code is wrong (mechanism, not restatement of the symptom).
• Evidence — the trace chain and the Phase 4 verification that confirms it.
• Proposed fix direction — one sentence targeting the root cause, not the symptom. Not an implementation.

Do not write diagnosis.md from this skill — that is diagnose.yaml's contract. Stop at the evidence-backed root cause.