/root-cause-delivery

name: root-cause-delivery
description: Use for a reported bug, regression, crash, failed workflow, or substantive code change that must reach a verified candidate rather than a local patch. Map the affected layer, freeze a bounded plan, require incident reproduction red-to-green or planned-change contract proof, force re-triage after two failed attempts, and close only with verified or explicitly blocked evidence. Do not use for a spelling-only documentation correction or an exploratory question with no implementation.

Root-Cause Delivery

The goal is not a green-looking diff. The goal is a candidate that fixes the observed contract and can advance toward release without reopening already proved work.

Use one durable case per substantive incident or code change:

.agent/delivery-cases/<case-id>/
  case.json
  evidence/

The installed `root-cause-delivery-guard.py` hook records a matching intent from an explicit bug/regression or substantive implementation request. It keeps source edits behind a valid `PLAN_FROZEN` case and will not allow a changed source tree to close while the case is incomplete. Harness records are never treated as source, so they stay writable before a case is frozen: delivery cases, `CONTINUITY.json`, `.agent/user-tasks/` and transfer contracts (`hooks/harness_records.py`). A bare background-task `<task-notification>` records no intent.

Workflow

1. Create the case before changing source:

   python ~/.claude/claude-code-config/hooks/root-cause-delivery-guard.py init <case-id> \
     --kind incident --summary "short observed failure"

Use `--kind change` for a feature or non-bug delivery task. The CLI binds the only active prompt intent automatically. If parallel sessions have active intents in the same repository, pass `--intent-id <id>` shown by the prompt receipt; it refuses to guess which session owns the case.

2. Fill `case.json` with observed facts, not a story:

• `observed.expected` and `observed.actual` for an incident;
• layer map: entrypoint, owning module, direct dependents, state or contract,

tests/probes, and release boundary;

• one causal hypothesis, bounded `fix_steps`, and a focused verifier argv.

Scope the *layer*, not the whole repository. The map asks which boundary owns the defect and which direct contracts can break; it is not permission for a speculative rewrite.

3. For an incident, capture the failing reproducer before source edits:

   python ~/.claude/claude-code-config/hooks/root-cause-delivery-guard.py capture <case-id> \
     --phase before -- <exact test command and arguments>

The command must fail. The helper stores argv, exit status, bounded raw output, and a digest under the case. Do not replace it with a different convenient test after the fix.

4. Freeze the plan, then implement:

   python ~/.claude/claude-code-config/hooks/root-cause-delivery-guard.py freeze <case-id>
   python ~/.claude/claude-code-config/hooks/root-cause-delivery-guard.py begin <case-id>

Make only the planned causal change. A cosmetic cleanup is allowed only when it is necessary to make the owning contract correct and is named in the plan.

5. If an attempt does not fix the reproducer, record it:

   python ~/.claude/claude-code-config/hooks/root-cause-delivery-guard.py record-failed-attempt \
     <case-id> --hypothesis "what this attempt tested" --changed-path src/module.py

After two failed attempts, stop editing the same area. Expand the owner map, record why the previous hypotheses failed, use a fresh evaluator when risk is high, then record re-triage:

   python ~/.claude/claude-code-config/hooks/root-cause-delivery-guard.py retriage <case-id> \
     --expanded-owner-path src/owner.py \
     --causal-hypothesis "a new, evidence-backed explanation"

6. For an incident, run the exact same reproducer after the fix. For a planned change, run the frozen `focused_argv` after implementation. In either case, use the exact argv written in `plan.focused_argv`:

   python ~/.claude/claude-code-config/hooks/root-cause-delivery-guard.py capture <case-id> \
     --phase after -- <the same test command and arguments>
   python ~/.claude/claude-code-config/hooks/root-cause-delivery-guard.py verify <case-id>

Before `verify`, a fresh reviewer who did not build the fix writes a receipt inside the repository and records it:

   Case: <case-id>
   Verdict: PASS
   Baseline cause: <exactly plan.causal_hypothesis>
   Owner boundary: <one exact path from layer.owner_paths>
   Reproducer: <the exact JSON argv observed before and after, or planned for a change>
   After result: the same argv exits 0 and the changed boundary is exercised

   python ~/.claude/claude-code-config/hooks/root-cause-delivery-guard.py record-independent-review \
     <case-id> --reviewer <fresh-session-id> --evidence .agent/delivery-cases/<case-id>/independent-review.md

The helper hashes the receipt and rejects a self-named review, a baseline cause that differs from the frozen hypothesis, an unmapped owner boundary, or a reproducer that differs from the captured red argv (or frozen change argv). The fresh reviewer starts from the case contract and repository state, not the builder's explanation or evidence. For an incident it must check that the red case failed for the claimed reason, rather than merely observing a nonzero exit.

7. Select the rest of the evidence by boundary and risk using `testing-strategy`. Run focused checks while iterating; run the complete candidate matrix once at the commit/merge/release boundary. Use `proof-verify` for a fresh verifier, and its stage ledger only when the accepted result feeds a real release, migration, signer, VM, or external service stage.

What Counts as Done

• `VERIFIED`: the