Prevent Recurrence

Prevent Recurrence

A fixed instance is not a fixed mistake. Use this procedure whenever a bug or an accepted review finding was caused by an agent's mistake, or by a pattern agents keep repeating, so the same class of mistake cannot come back unnoticed. It works in any repository and any workflow; it assumes nothing about the repository beyond what you find in step 3.

Skip it for ordinary feature work, rejected review findings, and failures with no mistake behind them (an outage, a flaky runner) unless they expose a missing guard.

1. Fix the instance

1. Reproduce the failure. Where a test is practical, write one at the observable surface (public function, route, CLI, rendered output) that fails on the current code, then fix the code and watch it pass. If no test is practical (prose, config, a one-off migration), say why in the closeout.
2. Write the mistake as a class in one sentence: "did X when Y, causing Z". The class sentence, not the instance, drives the rest of this procedure.

2. Find the class

1. Search the codebase for the same shape: the same call, import, literal, pattern, or missing pairing; parallel implementations of the same behavior (a twin path for retries, recovery, another platform, another plugin); and code written from the same template. Use text search plus any code-intelligence tool the session has (callers, importers, symbol search).
2. Fix the other instances in the same change when they are small and in the same area. Otherwise list each one with its path for the follow-up in step 6.
3. Keep the search commands. They go in the closeout so a reviewer can rerun them, and a search that found every instance with few false positives is often the start of a static check in step 4.

3. Learn the repository's own mechanisms

Find what exists before choosing a prevention; never assume a mechanism.

• Read the root and nearest AGENTS.md and CLAUDE.md (or equivalent) files for the changed paths, plus contributing and testing docs. Note any rule that already covers this mistake; if one exists, step 5 applies.
• Find the lint configuration and any custom rules, source-gate or policy scripts, allowlists and baselines, and what CI actually runs (workflow files, package scripts, Makefile, justfile).
• Learn the test conventions: where tests live, how they are named, and whether guard or contract tests already exist (tests that scan source files or iterate a registry are the usual home for a new guard).
• Read review checklists, PR templates, and review prompt packs if the repository has them. If a review already classified the finding's prevention (for example a workflow-code-review automation status), start from that classification and verify it against what you found.

4. Choose the highest rung that can catch it

Work down this trust ladder and stop at the first rung that can catch the class. Higher rungs enforce; lower rungs only advise.

Recognize the rung by asking, in order:

1. Could the code be shaped so the mistake does not compile or cannot be constructed?
2. Could a check find every instance from its text alone, with few false positives?
3. Can a test observe the mistake at a public surface without mocking the thing that went wrong? Prefer a test that enumerates all instances (every route, every registry entry, every skill file) over one that pins only the fixed one.
4. Does it need judgment? Then it is a rule, unless step 5 applies. Put it in the instruction file closest to the owning code, not the root by default: the nearest existing AGENTS.md (or the file the repository treats as canonical when AGENTS.md and CLAUDE.md both exist), or a new nested one only if the repository already uses nested instruction files. Keep it to one or two lines: the rule, why, and how to check.
5. Otherwise, a memory or notes hint, if the repository or workflow keeps one. A hint is never the only prevention for a correctness mistake: pair it with a rung 4 rule or a follow-up proposing a higher rung.