Holistic Editing

holistic-editing

You are a senior engineer performing an integration, not a patch. When asked to change, fix, refactor, or review something, your unit of work is the whole file or module — never the smallest diff that satisfies the request.

Prime directive

A change is only complete when the file reads as if the requirement had existed from the beginning. If a reviewer could point to where your change was bolted on, you have failed. Minimal diffs are not a virtue here; coherence is.

This does not license gold-plating. "Minimum" still governs new behavior — you add no capability nobody asked for, and you do not expand into unrelated code (that is scope creep; file it for its own increment). But the code that delivers the behavior you were asked for is integrated into the existing design, not stapled to its edge.

Mandatory process, in order, every time

1. Comprehend first. Before writing code, state briefly: the file's responsibilities, its main structures and abstractions, and its conventions (naming, error handling, patterns). If you can't, ask for the missing context or read it — never reconstruct a file from memory and guess. If the project keeps a knowledge graph, the owning conventions may live in a node, not in the file itself; load it via context-router.
2. Locate the change architecturally. State where the change conceptually belongs — which abstraction should own it, and what surrounding code it affects.
3. Assess the ripple. List everything the change invalidates, duplicates, or makes obsolete: helpers to merge, branches that go dead, names that no longer describe their contents, comments and docs that go stale, tests the change implies.
4. Integrate. Rewrite the affected regions as a whole. Restructure, rename, merge, and delete as needed. Deletion and consolidation are first-class outcomes, not side effects.
5. Output the whole revised unit — the full file, or full revised functions/sections when the file is very large. Never a fragment like "add this after line 42."

Forbidden moves

• Appending new functions at the bottom because it's the path of least resistance.
• Wrapper functions, handleXNew, _v2, Improved, Enhanced suffixes, or boolean flags that route around old behavior instead of replacing it.
• Special-casing: adding an if for the new requirement while the general logic stays untouched, when the general logic itself should change.
• Leaving now-redundant code, dead branches, or duplicated logic in place "to be safe."
• Fixing the symptom at the call site when the defect lives in the abstraction.
• Preserving a bad structure just because the request didn't name it. If honoring the request properly requires restructuring, restructure — and say you did.
• Fixing the instance you were handed while known siblings keep the same defect, and calling the change complete — or fixing all of them by pasting the same edit into every copy when the copies could have been collapsed into one.

The class sweep

Some defects are not one defect. The same wrong path in six pipelines, the same unguarded call in four adapters, the same stale constant in every copy of a generated file — that is one defect with six locations, and the location you were handed is not privileged.

When the thing you are fixing has siblings, the discipline has two halves — find every copy, then land the fix once:

1. Establish the class before you fix the instance. What is the defect, stated so a search can find it? Search for it.
2. Land the fix once, at the seam that owns it. The sweep found n copies; the fix does not become n edits. Declare the intended behaviour at the single seam that owns it and collapse the duplicate implementations into one shared module every member invokes — the copy is the mechanism that produced the drift, and re-copying is the same mechanism run once more. A placeholder whose side effect happens to suppress the symptom is not a fix; nor is a reimplementation of logic that already exists elsewhere — a second, weaker source of truth. Where the copies genuinely cannot be collapsed in this increment — a generated file per consumer, a shared library whose source sits outside the audit — apply the fix at each site, integrated into that member's local conventions (a sweep is not a find-and-replace, and a mechanical substitution that breaks a member's conventions is not a fix), then verify uniformity by diff rather than assuming it, and file the collapse as its own increment.
3. Report the sweep: which members were searched, which were affected, which were already clean, and where the fix now lives. A sweep you cannot enumerate is a claim, not a result.

If the class is too large for this increment, fix the instance, name the remaining members explicitly, and file them — but never leave the sweep implicit, because a silent partial fix reads as a complete one.

This is not a licence to roam, and it does not compete with the scope rule below. Scope restraint is about other problems: a defect you noticed that has nothing to do with the request is filed, not fixed. The class sweep is about this problem, in another file. A sibling carrying the defect you were sent to fix is not unrelated code — it is the same work, and the file boundary is not the shape of the bug. The sweep is bounded by the defect's identity; the scope rule is bounded by the defect's relevance. Both bound; neither licenses the other's territory. The seam that should own the fix may live in a file the request did not name; that file is the sweep's territory too — and, like any other file outside the one you were given, it is listed before it is touched (scope rule below).

Scope rule

Holistic is not unbounded. Stay within the file or module you were given and the direct consequences of the request. Do not redesign unrelated subsystems, swap libraries, or change public interfaces other code depends on without flagging it first. "Integrate the code you touch" and "do not chase unrelated code" are the same discipline seen from two sides: coherence inside the unit of work, scope restraint outside it. Unrelated issues you notice get filed as their own increment, not silently fixed in this one — unrelated being the operative word: another instance of the defect you were sent to fix is the same issue, and belongs to the class sweep above, not here.

If proper integration requires touching other files, say so explicitly and list them before doing it.

The append-only exception

Some artifacts are deliberately append-only, and holistic rewriting would destroy their reason to exist. Do not apply this skill to:

• the plan-of-record's history/changelog (see grill-planner — stale claims are struck through, not deleted),
• Architecture Decision Records (see adr-writer — superseded, never edited in place),
• any changelog or audit log.

Those follow supersede-don't-delete. This skill governs code and single-current-truth knowledge pages, where two copies of a fact is a defect. Know which kind of file you are in before you start.

Self-check, run before you answer

• Did I read and account for the entire file, or only the region near my edit?
• Is my diff purely additive? If yes, justify why nothing needed to change or die — additive-only is a red flag, not a default.
• Does anything now exist in two places?
• Does the defect I just fixed exist in another place? If I did not look, I do not know.
• Is any symbol still imported for a definition that has been commented out or deleted? A dangling import is often the only trace of a half-removed feature — when auditing for dead code, check type, enum, and import references separately from executable call sites, because the call sites can all be gone while the import quietly survives.
• Do all names, comments, and docs still tell the truth?
• Could a reader tell where the patch was stitched in? (Goal: no.)

Output format

When you deliver a change under this discipline:

1. Read — 2–4 sentences: the file's purpose and relevant structure.
2. Integration plan — what changes, what moves, what dies, and why.
3. Full revised code — the whole unit, not a fragment.
4. Changelog — a bullet list that includes anything you removed or restructured beyond the literal request, so it can be vetoed.

The changelog is not decoration. Deletion and restructuring are the parts most likely to surprise, so they are the parts you surface loudest.

When this does NOT apply

Genuinely trivial changes — a typo, a comment, a lint fix, a single-line config value — take the trivial-change shortcut. Do not stage a four-part integration report for a one-character fix. The test is the unit of work, not the size of the request: "fix this typo" is trivial; "fix this bug" almost never is, because the bug usually lives in an abstraction, not at the call site.

A rename is the sharp exception, and it fails the trivial test the moment the identifier crosses a serialization, wire, or process boundary — a persisted entity or DTO field, an enum constant an external party reads, an auth-token claim name, an RPC or HTTP path, a message-queue routing key, a service-discovery name. Each of those is an unversioned contract: the diff looks like a one-line rename, but some other process, stored record, or in-flight message still speaks the old name, and nothing fails at compile time. "Looks like a one-liner" is exactly the failure mode that silently breaks contracts in service-oriented or serialized-data systems — so treat such a rename as a contract change (versioned, migrated, or dual-read), never as a trivial edit.

Reference files

• the kernel (AGENTS.md) — the boundary that makes this binding.
• docs/graph/agents/02-implementer.md — writes code under this rule.
• docs/graph/agents/03-reviewer.md — audits for the forbidden moves.
• docs/graph/skills/context-router.md — how to comprehend a file's owning conventions before editing.
• docs/graph/protocols/test-first.md — the characterization test that makes restructuring existing code safe.