# Run-Error Ledger (refactor Step 0d)

Loaded on demand by `/multi-agent:refactor` Step 0d. The SKILL.md carries the step intro and its rules; this file is the full procedure.

## The ledger

```bash
LEDGER="$HOME/.claude/logs/multi-agent/errors-ledger.jsonl"
[ -f "$LEDGER" ] || echo "no run-error ledger yet - skip band F"
```

Each line is one run: `{ t, id, u, c, rp, ph, v, errs[] }`. The `errs[]` entries are cause tags (`<phase>:<cause>` halt reasons, `phase-<id>-failed`, `run-failed`).

## Procedure

1. Read the ledger (best-effort; a missing or unreadable file means skip band F, not a failure).
2. Group by error tag. For each tag compute: occurrences, distinct users affected, distinct repos, the phase it usually strikes, first + last seen, and which pipeline versions it spans (a tag that persists across versions is unfixed; one that stopped at a version is already resolved  -  do not re-raise it).
3. Rank by `occurrences x users-affected`. A failure that recurs across users or tasks is lived evidence, not a hypothesis  -  it outranks a speculative improvement.
4. For each surviving tag, trace it to the phase doc / script that emits that cause and propose the concrete fix.

This band mirrors the admin dashboard's "Gelişim alanları" panel, but reads the local ledger so it needs no auth and works offline.

## Transcript mining

Then read what the transcripts themselves record, which is the half no model noticed:

```bash
node "$HOME/.claude/scripts/learn-from-transcripts.mjs" --json
```

It correlates rather than interprets  -  a failed read against the read that then worked, an identical invocation that kept failing, a search that was too narrow, a call the user refused twice, a file too big to read whole. Dry run by default; `--apply` writes them to the learnings ledger as `source: transcript-mining` and renders a marked block in `CLAUDE.local.md`. Zero candidates alongside a non-zero `toolResultsExamined` means there was nothing to find; zero of both means the read is broken.

## Output (plan band F)

```
| # | Error tag | Occurrences | Users | Usual phase | Versions | Root cause (file) | Fix | In plan? |
|---|-----------|-------------|-------|-------------|----------|-------------------|-----|----------|
| 1 | 4:reviewer-json-invalid | 12 | 3 | 4 | 14.x-15.x | reviewer prompt lets prose leak | tighten schema instruction in phase-3-review.md | Yes (P0) |
| 2 | phase-3-failed | 5 | 2 | 3 | 15.0.x | build step misses a stack toolchain | add preflight in phase-2-dev.md | Yes (P1) |
```

## Rules for this band

- The ledger is evidence of the past, not a spec. A tag that stopped recurring after a version bump is resolved  -  report it as resolved, do not add a plan item.
- Never quote a user's identity as blame. The `u` field is for counting distinct affected users, not for naming anyone in the plan.
- If the ledger is empty or absent, skip band F silently  -  it is additive signal, never a gate.