Distill, do not accrete

This is a recommendation, not a requirement. Use it when code or knowledge keeps growing around a structure that no longer matches what you understand.

The recommendation

Systems should become simpler as understanding improves. When new knowledge changes the right design, reshape the owning structure as if that knowledge had always been known. Preserve the invariant. Remove what the new structure makes unnecessary.

Do not preserve an explanation of a failure merely because the failure happened. Once the cause is understood and fixed, state the current truth in its simplest useful form.

In knowledge

Update the document that owns the answer. Replace stale guidance instead of appending a correction. Consolidate overlapping documents and archive work whose durable substance now lives elsewhere. When one document mixes several objects of attention, shape it before refining it. Introduce a type, rule, or index only when a repeated need earns it; for a type, When a kind gets its own type names the signs.

Keep the current status of knowledge explicit. Once a decision is accepted or a way of working is demonstrated, replace obsolete hypothesis framing in the current owner. Separate established practice from open questions about its scope, quality, cost, or comparative advantage. Reopen a settled question when relevant evidence or authority changes, not merely because a new example appears.

In code

Fix the layer that owns the invariant. Update the callers you control. Remove obsolete paths, flags, compatibility layers, and tests of mechanisms that no longer exist. Keep or rewrite the tests that protect the invariant.

What to preserve

Distillation is not deletion for its own sake. Preserve evidence, provenance, pinned historical records, real disagreement, unresolved uncertainty, and material required for legal or audit purposes. Do not rewrite a record of what happened as if it had predicted the future.

Exploration may expand before it converges. Research notes, competing hypotheses, and temporary work are useful while a meaningful question is open. Define what the research should inform: a decision, a material uncertainty, or a comparison that someone uses. Missing information alone does not justify another profile, experiment, or document. Distill the result into its owner and stop when the question is sufficiently answered; retain a concrete reason to revisit it.

A small loop

Examples

Several notes explain the same decision. Fold the current answer and necessary evidence into the owning decision document, then archive the superseded notes.

A fixed bug leaves a long warning in the interface. Remove the warning when the interface can state the normal behavior clearly.

A repository-owned API changes. Update its callers and remove the old alias instead of maintaining two internal vocabularies.

One document suggests a new category. Use a clear title first, and create a document type once one of the signs in When a kind gets its own type appears.

A useful prompt

Ask your agent: "Read the current system and find one place where newer understanding has accumulated around an older structure. Propose the smallest rewrite that preserves the invariant and evidence while removing obsolete material. Update the owner instead of creating a sibling note."