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.

FileKindSize
SKILL.mdskill md3.7 KB
references/LOCALIZATION.mdmarkdown1.6 KB
references/examples.mdmarkdown685 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
}
```
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated 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: 198kUpdated Claude CodeCodexVerifiedInstall