gilde

← All craftbooks

Root-Cause Investigation

Review and QAevalv2.0.8released 2026-09-05

Debug systematically: reproduce the failure and find the true root cause before changing any code, then fix and verify.

Steps

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

  1. Reproduce and bound the failuredebugging engineerentry

    Establish a stable failing case, expected behavior, environment, and blast radius.

    Show working prompt
    Read the request, relevant code, existing tests, logs, and configuration. Reproduce the problem with the smallest safe case you can run. Record exact inputs, expected and actual results, environment details, frequency, and whether the failure is deterministic. If it cannot be reproduced, document the attempts and the missing observation needed; do not invent a cause or edit production code.

Observable handoff: write the completed result to `investigations/reproduction.md` in the workspace with `write_file`. Do not merely describe what the file would contain. Re-read it with `read_file` before finishing this phase and repair any incomplete sections.
  2. Prove the root causeroot-cause analyst

    Test competing hypotheses and identify the causal mechanism before modifying code.

    Show working prompt
    Use `investigations/reproduction.md` to form at least two plausible hypotheses. Trace the relevant execution and data paths with workspace search and file-reading tools. For each hypothesis, run a discriminating experiment and record its predicted versus observed outcome. Name the first bad state or decision, explain how it produces the symptom, and check for sibling cases. Do not change source code in this phase.

Observable handoff: write the completed result to `investigations/root-cause-analysis.md` in the workspace with `write_file`. Do not merely describe what the file would contain. Re-read it with `read_file` before finishing this phase and repair any incomplete sections.
  3. Implement the smallest fix and verify itsoftware engineer

    Correct the proven mechanism and demonstrate both regression coverage and non-regression.

    Show working prompt
    Read both investigation files. Implement the smallest maintainable change that breaks the documented causal chain. Add or strengthen a regression test that fails on the old behavior and passes with the fix. Run the focused test, relevant neighboring tests, and any proportionate static checks. Record exact changed paths and exact verification commands with exit results. If the environment prevents a check, label it unverified and explain what is needed to run it.

Observable handoff: write the completed result to `{{workPath}}/reports/root-cause-investigation.md` in the project's artifacts drawer with `write_artifact`. Do not merely describe what the file would contain. Re-read it with `read_artifact` before finishing this phase and repair any incomplete sections.
  4. Evaluate the deliverabledebugging reviewer

    Independently grade the observable deliverable and route it to finish, repair, or user escalation.

    Show working prompt
    Review `{{workPath}}/reports/root-cause-investigation.md`, `investigations/reproduction.md`, `investigations/root-cause-analysis.md` against every criterion below. Inspect the underlying evidence files named by the workflow; do not grade from the author's summary alone.

1. The failure is reproducible or the report explicitly stops without claiming an unproven diagnosis.
2. Competing hypotheses were separated by recorded experiments rather than intuition.
3. The stated root cause includes a causal chain from first bad state to observed symptom.
4. The change is limited to that causal mechanism and covers identified sibling cases.
5. A regression test and neighboring checks have concrete, credible results with no fabricated execution evidence.
6. The report identifies changed files, residual risk, and a viable rollback.

Open `{{workPath}}/reports/root-cause-investigation.md` with `read_artifact`. Open `investigations/reproduction.md`, `investigations/root-cause-analysis.md` with `read_file`. Write the evidence-backed review to `{{workPath}}/reviews/root-cause-investigation-review.md` in the artifacts drawer with `write_artifact`. Give each criterion a PASS or FAIL with a concrete path, excerpt, measurement, or observed behavior. End with exactly `Verdict: PASS` or `Verdict: REVISE`. Then use `advance_task_step` for the active task: PASS routes to `finish`; REVISE routes to `repair` for review rounds 1 through 2, and the 3th REVISE routes to `needs-user`. Never route to finish while a criterion is unmet.
  5. Repair the deliverablesoftware engineer

    Fix only the concrete gaps from the latest independent review.

    Show working prompt
    Read `{{workPath}}/reviews/root-cause-investigation-review.md` with `read_artifact` and repair every failed criterion in `{{workPath}}/reports/root-cause-investigation.md`, `investigations/reproduction.md`, `investigations/root-cause-analysis.md`. Make changes on each file's declared surface (`write_artifact` for artifact inputs, `write_file` for workspace inputs), not in task notes or a reply. Preserve evidence that already passed. Re-run or re-check anything the reviewer found unproven. Ensure `{{workPath}}/reports/root-cause-investigation.md` is genuinely updated this turn so the repair is observable, then hand it back for independent evaluation.
  6. Finishproject lead

    All deterministic and reviewer criteria passed.

    Show working prompt
    The independent review passed. Read `{{workPath}}/reviews/root-cause-investigation-review.md` with `read_artifact`, then use `write_task_note` to record a concise DONE summary with the final deliverable paths (`{{workPath}}/reports/root-cause-investigation.md`, `investigations/reproduction.md`, `investigations/root-cause-analysis.md`) and the evidence that each acceptance criterion passed. Report DONE without starting new work.
  7. Escalate unresolved concernsproject lead

    The bounded repair loop ended without a defensible pass.

    Show working prompt
    The deliverable did not pass after 3 review rounds. Do not claim success. Read `{{workPath}}/reviews/root-cause-investigation-review.md` with `read_artifact`, then use `write_task_note` to record DONE_WITH_CONCERNS: the unmet criteria, what was attempted, the affected paths, and the smallest user decision or missing input needed to continue.

Triggers

Phrases that suggest this craftbook to a crew.

Source

View this craftbook on GitHub · MIT license