Playbook: Recovery
Objective
Restore a known-good state after Claude Code (or any agent) produces wrong, sprawling, or confidently broken changes — then re-attempt with tighter controls — without spending hours "prompting the mess into shape."
When to use
Diff is incoherent; tests were weakened to pass; architecture sprouted a v2 package; session is thrashing; or a merged agent PR is burning production. Mild fixups inside an otherwise good plan are not recovery — just continue the feature playbook.
Inputs required
- Git history you trust (last known-good commit/tag).
- What you were trying to achieve (original goal/spec).
- Symptoms (failing tests, bad behavior, review rejects).
- Willingness to throw away agent work (recovery fails when you refuse to revert).
Step-by-step process
1. Stop — do not "one more fix"
End the session. More tool calls on a polluted context usually compound damage (Stuck Loops and Thrash).
2. Classify blast radius
| Class | Signs | Default move |
|---|---|---|
| Local mess | Uncommitted or one PR; allowlist exploded | git checkout / revert PR |
| Mixed bag | Some increments good, last ones bad | Revert commits/files selectively; keep green slice tags |
| Merged | On main | Revert PR or forward-fix with tests; treat as mini-incident |
| Data/schema | Migrations applied | Do not blind-revert; human-owned recovery plan |
Schema/data damage is What Not to Delegate territory — agent assists diagnosis; you own the cutover.
3. Revert or quarantine aggressively
Prefer revert over repair when the agent touched >~15 unrelated files or edited tests to match bugs.
# Human-run examples — adapt to your git practice
git switch main
git revert <merge-commit> # if merged
# or
git restore --source=<good> -- <bad-paths>Quarantine pattern: leave good subdirectory changes; restore package.json, lockfiles, and test expectations from known-good if the agent "fixed" them.
4. Context reset
New Claude Code session (or /clear). Old transcript contains failed plans the model will keep trying to satisfy. Load only: CLAUDE.md, the amended spec, and a short incident note.
5. Write the incident note (durable)
## Recovery note — <date>
- Goal was: <...>
- What went wrong: <symptoms, paths>
- Root cause hypothesis: <ambiguous prompt | missing spec | no allowlist | thrash>
- Reverted to: <commit>
- What we keep: <nothing | slice 1–2>
- Next attempt constraints: <tighter allowlist, tests first, plan mode>Commit this under docs/ or the spec folder so the next session sees it.
6. Characterize and re-spec before re-prompting
If behavior is unclear after the mess:
Read the recovery note and <paths>.
Propose characterization tests for the behaviors we must preserve.
Do not re-implement the feature. Stop after tests (or a test plan if hooks needed).Amend the spec: add the missing constraints that the failed run invented wrongly (as non-goals or explicit decisions). See Keeping Specs Alive.
7. Re-plan with stricter controls
Fresh plan for <goal> given recovery note + amended spec.
Mandatory:
- Plan mode
- File allowlist ≤ <n> files
- Stop-and-ask denylist: deps, schema, test expectation changes
- Increment 1 = <smallest proof>
- Evidence required
Do not edit until approved.Stack Control Techniques. If the original task was oversized, switch to Large Tasks.
8. Re-implement and review harder
Smaller increments; Reviewing AI PRs three-pass on the retry. If the retry fails the same way once, stop again — change the process (spec, seams, human design), not the model temperature of hope.
Human review points
- Revert decision — yours; agents hate throwing work away.
- Schema/data path — yours alone.
- Amended spec — you add the missing constraints.
- Approval of the recovery plan — before new edits.
- Postmortem one-liner in
CLAUDE.mdif the failure will recur (never-do).
Expected artifacts
Known-good tree · recovery note · amended spec · characterization or regression tests · narrower successful PR · optional CLAUDE.md never-do.
Common failures
| Symptom | Root cause | Early detection | Fix |
|---|---|---|---|
| Three-hour "almost fixed" | Refused to revert | File churn rising | Hard revert; reset |
| Retry repeats the same design | Spec never amended | Same silent decisions | Write non-goals; plan mode |
| Restored code, kept bad tests | Partial quarantine | Test diff from main | Restore test expectations too |
| Agent continues from old chat | No context reset | Session references failed plan | /clear or new session |
| Migration half-applied | Agent "fixed forward" | Prod/stage drift | Human migration playbook; stop agent |
Recovery strategy
This is the recovery strategy. Meta-failure (recovery itself thrashing): pair with a human, disable auto-approve permissions, and implement the smallest proof manually or with autocomplete-only assistance until the seam is obvious.
Acceptance criteria
- [ ] Tree is known-good or explicitly quarantined with green gates
- [ ] Failed session context discarded
- [ ] Recovery note + amended spec committed
- [ ] Retry uses tighter allowlist / plan mode / evidence
- [ ] Root process gap addressed (CLAUDE.md never-do or checklist)
- [ ] No schema/data roulette delegated to the agent
Related
- Stuck Loops and Thrash — why stopping is correct.
- Control Techniques — tighten on retry.
- Large Tasks — if size caused the failure.
- Legacy Refactor — characterization-first when behavior is unclear.
- Hallucination and False Confidence — distrust claims during triage.
- Production Debugging — if the bad output is already live.