dvy1987/agent-loom / .agents/skills/fault-localize
fault-localize
VerifiedFind 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 3.7 KB |
| references/LOCALIZATION.md | markdown | 1.6 KB |
| references/examples.md | markdown | 685 B |
references/LOCALIZATION.md
View on GitHub# Localization Procedure
REFLECT-style loop: diagnose → targeted replay → verify outcome flip. Pairs with `run-trace` evidence.
---
## Step 1 — Scan trace chronologically
```bash
python3 .agents/skills/run-trace/scripts/trace_query.py <trace> timeline
```
Find the **earliest** record where:
- `error` is non-null, OR
- operational `output_ref` contradicts prior cognitive `expected` for same `step_id`
That record's `step_id` is the **suspected origin** (first divergence).
---
## Step 2 — Hypothesis (evidence-bound)
```markdown
suspected_step_id: Sx
hypothesis: [one sentence citing output_ref/error]
layer: [tooling | code | plan | environment]
```
No vague "something went wrong."
---
## Step 3 — Targeted repair
| Layer | Action |
|-------|--------|
| tooling | Different tool/flags |
| code | Minimal fix via `debug-and-fix` or `safe-change` |
| plan | `dynamic-routing` revision |
| environment | Fix deps/config; replay from Sx |
---
## Step 4 — Replay from suspected step
Re-execute from `suspected_step_id` forward — not full run from S1 unless plan layer fault.
---
## Step 5 — Outcome flip
| Before | After | Verdict |
|--------|-------|---------|
| fail | pass | **Attributed** — record intervention |
| fail | fail | Wrong localization — back to Step 1 with next candidate |
| pass | pass | No fault in trace — check success criteria |
---
## Attribution record
Append to `.agent-loom/traces/<run-id>-attribution.json`:
```json
{
"run_id": "...",
"suspected_step_id": "S2",
"hypothesis": "...",
"repair": "...",
"outcome_flip": true
}
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |