Fault Localize

You find the earliest decisive divergence in a trace, hypothesize cause from evidence, apply a targeted repair, replay from that point, and verify an outcome flip. No vague retries.

Hard Rules

Require a trace file (.agent-loom/traces/<run-id>.jsonl) or reconstruct from session tool history. Follow references/LOCALIZATION.md — earliest error/divergence wins. Hypothesis must cite output_ref or error from the trace record. Replay from suspected step — not full blind restart unless plan-layer fault. Record attribution with outcome_flip boolean. Route code defects to debug-and-fix; plan faults to dynamic-routing.

---

Workflow

Step 1 — Load trace

Run trace_query.py timeline and errors. If no trace, build minimal timeline from session history.

Step 2 — Identify suspected step

Earliest record with error or output contradicting expected. State suspected_step_id.

Step 3 — Write hypothesis

Three lines max — cite evidence. Classify layer.

Step 4 — Propose targeted repair

One intervention matched to layer. Not a kitchen-sink fix.

Step 5 — Replay and verify

Re-run from suspected step. Compare outcome.

Step 6 — Attribute

Write attribution record. If no flip, consider next candidate step.

---

Gotchas

• Latest error ≠ earliest cause — always scan chronologically.
• Fixing symptoms downstream masks upstream plan errors.
• Flaky tests need two replays before attributing.

---

Output Format

## Fault localization — [run_id]

Suspected step: **Sx** @ [ts]
Hypothesis: [evidence-cited]
Layer: [tooling|code|plan|environment]

Proposed repair: [one intervention]
Replay result: [pass|fail]
Outcome flip: [true|false]

Attribution: `.agent-loom/traces/[run_id]-attribution.json`
Next: [resume plan | debug-and-fix | escalate]

---

Examples

Teaser: Trace shows S1 pass, S2 npm test fail → hypothesize missing env → repair .env.example → replay S2 → flip true.

Full pairs: references/examples.md

---

Common Rationalizations

Excuse	Reality
"Last error is the cause"	Downstream errors are often symptoms.
"Retry whole run"	Expensive; masks localized fix opportunity.
"Guess and patch"	Hypothesis without evidence → wrong attribution.
"Trace is optional"	Localization without trace is reconstruction guesswork.
"One flip proves root cause"	Flaky tests need confirmatory replay.

Verification

• Suspected step is earliest divergence
• Hypothesis cites trace evidence
• Attribution record written
• Layer-appropriate handoff if not fixed

Red Flags

• Hypothesis with no trace citation
• Full rerun without identifying suspected step
• outcome_flip true on single flaky test

Prune Log

Last pruned: 2026-07-05

• Initial release from high-leverage skill spec (Skill 4 family)

Impact Report

Localize: [run_id] | Suspected: [step] | Flip: [bool] | Layer: [layer]