gilde

← All craftbooks

Root-Cause Investigation

Review and QAevalv1.0.0released 2026-06-05workflow: build-loop

Debug a defect or production incident down to its true root cause and document the diagnosis with evidence, instead of patching the first symptom. First reproduces the failure reliably and locks what 'understood' means (a confirmed repro, the failing assertion, the exact trigger condition), then narrows the cause by forming and testing hypotheses, bisecting, reading stack traces and logs, and tracing the data path until one hypothesis is proven, then writes a root-cause report with the evidence chain, the smallest fix, and how to prevent recurrence. Use this for debugging, root-cause analysis, investigating a bug or flaky test, diagnosing an incident, or figuring out why something breaks — it produces a proven cause backed by evidence, not a guess.

Steps

Entry step: reproduce. Each step names the specialist role it wants; the full working prompt is expandable.

  1. Reproduce & scopereviewerentry

    get a reliable repro, lock what 'understood' means

    Show working prompt
    Step 1: Capture the symptom precisely — the exact error message, stack trace, failing test, or observed wrong behavior, and the environment it occurs in. Step 2: Establish a RELIABLE reproduction: the minimal steps/inputs that trigger the failure every time. If it is intermittent, note the frequency and any conditions that change it. Step 3: Pin down the boundary — what is the last known-good state (commit, input, version) and the first known-bad state. Step 4: Write an acceptance-criteria checklist for the investigation, e.g. 'the repro triggers the failure deterministically', 'the exact failing line/assertion is identified', 'the cause is proven by evidence, not asserted', 'the proposed fix is the smallest change that resolves the repro'. Step 5: Record the repro steps and the known-good/known-bad boundary to `write_task_note` AND `notes/reproduce.md`. No fix yet — confirm you can make it fail on demand first.
  2. Narrow the causereviewer

    form + test hypotheses until one is proven

    Show working prompt
    Step 1: From the repro, list 2-4 concrete hypotheses for the cause, each falsifiable (e.g. 'the input is undefined here', 'the off-by-one is in this index', 'the race is between A and B'). Step 2: Test the cheapest hypothesis first — add logging/asserts, set a breakpoint, bisect the diff (`git bisect` or binary-search the change), or read the implicated code and trace the data path. Step 3: Record what each experiment PROVED or DISPROVED — do not move on from a hypothesis on a hunch; require evidence. Step 4: Iterate until exactly one hypothesis is proven: you can point to the precise line and explain the mechanism (why this input + this code produces this failure). Step 5: Confirm the root cause by predicting a NEW case it explains and verifying that prediction. Good looks like: an evidence chain from symptom → mechanism → root line, not 'I think it is the cache'. Stage the hypothesis log to `write_task_note`. Do not write the final report yet.
  3. Write the root-cause reportreviewer

    diagnosis, evidence chain, smallest fix, prevention

    Show working prompt
    Step 1: Open `root-cause.md` and write a one-paragraph '## Summary' stating the root cause in plain language and where it lives (file:line). Step 2: Add '## Reproduction' with the deterministic repro steps. Step 3: Add '## Evidence' as an ordered chain: symptom → each experiment and its result → the proven mechanism. Step 4: Add '## Fix' describing the SMALLEST change that resolves the repro (and why a smaller/larger fix is wrong), with the diff or exact edit. Step 5: Add '## Prevention' — the test or guard that would have caught this and should be added. Every claim in the evidence chain must be backed by an experiment result, not assertion. On a loop-back, fix only the named gaps. `write_task_note` the report path and the proven root-cause location.
  4. Evaluatereviewer

    Grade the deliverable against every acceptance criterion. All pass → finish; any fail → loop back and fix the gap.

    Show working prompt
    Open `root-cause.md` and grade it against the reproduce checklist. Check EACH criterion and write PASS/FAIL with a one-line reason: (1) the reproduction is deterministic and documented; (2) the root cause is pinned to a specific file:line/mechanism, not a vague subsystem; (3) the evidence chain actually proves the cause (each link backed by an experiment result); (4) the proposed fix is the smallest change that addresses the cause and would resolve the repro; (5) a prevention test/guard is specified; (6) the diagnosis is a proven mechanism, not a guess. If any criterion fails, name the exact gap and loop back.

Then route — this is the whole point of the loop:

- **Every criterion PASSES →** call `advance_task_step({ ref, stepId: "evaluate", next: "finish" })`.
- **Any criterion FAILS →** write the specific gaps to notes, then call `advance_task_step({ ref, stepId: "evaluate", next: "report" })` to loop back. The builder fixes exactly those gaps.

Never route to `finish` while any criterion is unmet. The build phase's completion gate already blocked a grossly-incomplete deliverable; your job is the judgment an automated check cannot make (does it actually work, read well, look right). After ~3 unproductive loops, stop and report DONE_WITH_CONCERNS so the user can step in.
  5. Finishdeveloper

    All acceptance criteria met. Stamp a short summary and report DONE.

    Show working prompt
    Every acceptance criterion passed. Write a one-paragraph DONE summary to task notes via `write_task_note`: what was built, the deliverable path(s), and a one-line confirmation that each criterion is met. Then report DONE.

Triggers

Phrases that suggest this craftbook to a crew.

Source

View this craftbook on GitHub · MIT license