Skip to content

dvy1987/agent-loom / .agents/skills/fault-localize

fault-localize

Verified

Find the earliest decisive failure in an agent run trace and propose an evidence-backed targeted repair. Load when a run failed, results are wrong, or the user asks what went wrong in an agent session. Also triggers on "localize the fault", "first incorrect step", "debug this run", "trace attribution", "why did the agent fail", or after run-trace captures errors. Pairs with debug-and-fix for code defects and dynamic-routing for plan faults.

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

ExcuseReality
"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]
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 319kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 319kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 319kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 196kUpdated Claude CodeCodexVerifiedInstall