Failure as Institutional Memory

Preserve past incidents as concrete specifics, not abstract admonitions. Only what the model has no way of knowing — what actually happened here — is worth writing down; adding what the model already does just adds noise.

Problem

Agents don't learn across sessions. The landmine stepped on last week gets stepped on again this week. The human side remembers "I said this before"; for the model, every time is the first time. So another line gets added to the instruction file: "check carefully." But this kind of writing doesn't work — the official docs name this exact style of writing noise (see in Practice). The result: incidents keep repeating, the instruction file keeps growing, and the growth crowds out the other instructions that get skipped.

Context

Applies when:

• The same failure happened twice, or even once at high cost
• The failure has reproducible conditions — it can be written as: in this situation, doing this operation produces this result
• It's a fact the model has no way of knowing — a quirk specific to this environment, the actual outcome of something that happened here before

Does not apply when:

• It merely restates the model's default behavior. Things like "don't claim done until tests pass" are what current models already do by default; writing it down has little marginal value (this is a judgment, not a measurement — an audit finding from one individual environment, which independently matches the official docs' "add noise ... already optimized." Both discussed in Practice)
• The failure was one-off and its reproducible conditions can't be pinned down. A memory with no stated conditions can't be matched against next time
• Code or tests already have a home for it. A quirk a parser trips on belongs in the parser's tests, not the instruction file. Writing down in human language a failure a machine can already stop is putting it in the wrong place

Boundary with neighboring patterns:

• Resident Context Inventory — this pattern adds to memory; that pattern subtracts from it. The two are in direct tension. What resolves the tension is this pattern's condition: write down only what the model has no way of knowing
• Instruction Layering and Scoping — where that memory takes effect is that pattern; what to write is this pattern
• Rules Ranked by Binding Force — what binding force to give the memory is that pattern
• Separating Mechanical Gates from Semantic Gates — a failure a machine can stop becomes a gate. What goes into instructions is only the failure a machine cannot judge
• Read-and-Discard Isolation — what to expel from context is that pattern; what's worth keeping in context is this pattern. Two ends of the same question: what earns the right to occupy context

Solution

Why this works. The model already has the general knowledge. "Double-check your work," "don't miss anything," "be careful" — it read countless instances of these at training time. Adding them to the instruction file adds nothing to what the model already holds. And what adds nothing still costs rent every single turn.

What the model doesn't have is what actually happened here. In this environment, in this procedure, under this condition, what broke and what it cost. This exists nowhere in the training data and can only be supplied from outside, in principle. So the value of institutional memory is set by this difference:

Value of writing it = incident detail − what the model already knows generally

"Check carefully" has a gap of zero, because it extracts only the general lesson from the incident and writes down nothing else. The moment an incident gets abstracted, its value as writing disappears. Institutionalizing memory means preserving the concrete against the pull toward abstraction. This runs counter to intuition — we normally try to remember lessons by generalizing them.

It's also worth noting that writing concretely makes things shorter. An abstract admonition has unlimited scope, so it can be elaborated on forever. A concrete precedent points to exactly one condition, so it fits in a single line. Length and effectiveness are, here, inversely correlated.

Keep the form as a triple: symptom (what happened), condition (how it reproduces), outcome (what actually resulted). A memory whose condition can't be written down can't be matched against next time, so don't keep it. A memory whose outcome can't be written down has no known weight, so it can't be prioritized.

The triple has one more benefit: it can be deleted once its condition disappears. No one can judge when an abstract admonition has become unnecessary, so it stays forever. A concrete precedent gets discarded along with the procedure it was tied to, once that procedure is gone. Writing institutional memory concretely also means writing it in a form that can later be inventoried (Resident Context Inventory).

Trade-offs

Advantages

• Shorter than an abstract admonition. In one individual repository, each item in a verification checklist is tied to a past incident with its actual cost attached, and its byte count was a fraction of an abstract instruction like "double-check carefully" (Measured, see in Practice). Shortness can be measured; "works better" was not measured — the grounds for that come from the official docs instead (specificity matters / add noise, see in Practice).
• Can be inventoried later. Because the reproducible condition is stated explicitly, deletion can be judged once that condition disappears. An abstract admonition allows no such judgment and keeps paying rent forever.

Costs

• Adds to what's resident. A memory starts charging rent every turn the moment it's written. The official docs state plainly that an overly long instruction file can cause some instructions to be overlooked (see in Practice), so adding a memory also dilutes the other instructions. This pattern is in direct tension with Resident Context Inventory, and that tension doesn't go away.
• A memory is not a guarantee. The official docs state plainly that instruction compliance is non-deterministic (see in Practice). Writing it down doesn't mean it never happens again. A failure that must be stopped deterministically belongs in a mechanical gate, not an instruction (Separating Mechanical Gates from Semantic Gates).

GitHub Copilot in Practice

github.com — custom instructions for code review

What this section's Official quotes actually cover

Every quote below describes custom instructions for Copilot code review specifically. Do not cite it as a benchmark for instruction files in general. Neither the numbers nor the advice should be extended beyond what the source text names.

Source: Using custom instructions to unlock the power of Copilot code review (retrieved 2026-07-16, read in full).

The official docs devote a section to "instructions not to write," and its last category is exactly the heart of this pattern Official:

Vague quality improvements:

• Be more accurate
• Don't miss any issues
• Be consistent in your feedback

These types of instructions add noise without improving Copilot's effectiveness, as it's already optimized to provide accurate, consistent reviews.

"Be more accurate," "don't miss any issues," "be consistent" are stated plainly to add noise without improving effectiveness. The reason is given too — already optimized, meaning it's what the model already does. This is one of the few places where Solution's "zero gap, zero value in writing it" is confirmed in the official docs' own words.

The same page states the other side too Official:

• Non-deterministic behavior: Copilot may not follow every instruction perfectly every time.
• Context limits: Very long instruction files may result in some instructions being overlooked.
• Specificity matters: Clear, specific instructions work better than vague directives.

All three connect directly to this pattern's trade-offs. Being specific works (specificity matters), but the more you write, the more gets overlooked (context limits), and even so, there's no guarantee it's followed (non-deterministic).

Granularity and an upper bound are given too Official:

Begin with 10–20 specific instructions that address your most common review needs, then test whether these are influencing Copilot code review in the way you intended.

Best practice: Limit any single instruction file to a maximum of about 1,000 lines. Beyond this, the quality of responses may deteriorate.

The same page's Troubleshooting section lists "Instruction file is too long (over 1,000 lines)" as the top cause when instructions get ignored. This amounts to the official docs naming, as a root cause, exactly what happens at the end of continually adding more memories.

Observed in real-world use

In one individual repository (an audit as of 2026-07-07, Claude Code environment, n=1), this pattern was observed to have been implemented independently. This is not written as a general law. What follows separates what was observed from the judgment drawn from it.

What was observed Measured

• Each item in the verification checklist is tied to a past incident with its actual cost attached (the incident's amount and subject are financial information and are not brought into this catalogue)
• The byte count of that description is a fraction of an abstract instruction like "double-check carefully"
• A fix commit bundled 44 lines of regression tests with a 2-line fix. That repository's fix-commit rate is 3.3%, with zero reverts

What was not observed (the auditor's judgment, not Measured)

• The same audit concludes this design "has a far higher effect on preventing recurrence." But no counterfactual was run — no one counted the recurrence rate under an abstract-admonition regime. The grounds for effectiveness aren't a measurement; they come from the official docs (specificity matters / add noise)
• The same audit also flagged the rules' model-babysitting tendency, judging that things like "don't claim done until tests pass" are current models' default behavior and so have little marginal value. This, too, is a judgment, not a measurement. Still, it means something that the official docs' "add noise ... already optimized" and an independent individual-environment audit reach the same conclusion — the weight of the evidence comes from the agreement itself

This distinction is the convention itself

Byte counts and the fix-commit rate are visible without running a counterfactual. "Has a higher effect on preventing recurrence" is visible only by running the abstract version and counting. The former is Measured; the latter is a judgment. Placing both under the same label leaves the reader unable to judge their weight, and Measured degrades from "observed" into just another name for "the author thinks so." Measured can only cover what's visible without running a counterfactual.

Equivalents in other tools

Where it's placed varies by tool, but the structure doesn't. For Copilot it's .github/copilot-instructions.md or *.instructions.md (source above); for Claude Code it's CLAUDE.md.

All of these are names for the mechanism, not for this pattern (what to write). The mechanism only provides a place to put things; it doesn't decide what belongs there.

Also Known As

Name	Source
Custom instructions / instruction file	Primary — but this names the mechanism, not this pattern (source: in Practice section above)
Failure as Institutional Memory	Descriptive — this catalogue's descriptive name; no primary source uses it

The official docs give a name only to the container (custom instructions, CLAUDE.md). The practice of "writing past incidents concretely into that container" has, as far as this catalogue could confirm, no established name. Using the container's name for the practice's name invites the misreading that "having an instruction file" equals "doing this practice." In reality, the same container can just as easily be filled with abstract admonitions, and the official docs call that noise. Since the container and its contents are separate matters, the contents side is given a name of its own. Descriptive marks a name coined by this catalogue.

Related

• Read-and-Discard Isolation — what to expel from context is that pattern; what's worth keeping is this pattern. Two ends of the same question: what earns the right to occupy context
• Resident Context Inventory — this pattern adds to what's resident; that pattern subtracts from it. Direct tension. What reconciles the two is the condition "write only what the model has no way of knowing" — writing concretely also makes later inventory possible
• Separating Mechanical Gates from Semantic Gates — a failure a machine can judge becomes a gate, not an instruction. What gets written into instructions is only the failure a machine cannot stop
• Instruction Layering and Scoping — where memory takes effect (its scope) is that pattern. This pattern deals only with what to write
• Rules Ranked by Binding Force — what binding force to give the retained memory is that pattern
• If reading just one more next: Resident Context Inventory — the memory just retained is itself resident content, and it's next to count its rent