git:20260930.dd7591d to git:20261006.fa6eac5

---

name: holistic-editing

description: 'The discipline for any change, fix, refactor, or review whose unit of work is larger than a trivial one-liner. Use whenever you edit existing code or a knowledge page — the unit of work is the whole file or module, never the smallest diff that satisfies the request. A change is complete only when the file reads as if the requirement had existed from the beginning: no bolted-on functions, no _v2 wrappers, no special-case branches around logic that should itself change, no now-dead code left "to be safe." Coherence outranks minimal diffs. Load this before editing a file of any substance; it governs how implementer, reviewer, and every specialist touch existing files.'

id: skill.holistic-editing

tier: 2

kind: skill

origin: seed

title: holistic-editing — every change is an integration into the whole file, never a bolted-on patch

owns:

- holistic-editing.method

- holistic-editing.forbidden-moves

- holistic-editing.class-sweep

requires:

peers:

- skill.context-router

- protocol.test-first

load_when:

- "edit an existing file of any substance"

- "refactor without bolting on"

- "review a diff for coherence"

- "additive-only diff smells wrong"

- "same bug probably exists elsewhere, fix one or all"

- "rename crossing a serialization or wire boundary"

- "nothing uses this, delete dead code or an unused file"

prevents: Changes landed as the smallest diff that satisfies the request — bolted-on functions, _v2 names, and a file whose design is the fossil record of every past edit.

est_tokens: 2720

---

# 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**.

"Minimum" still governs *new behavior*: add only the capability the

request asks for (Scope rule below). The code that delivers it is

integrated into the existing design, not stapled to its edge.

## Process, in order

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, read

the file or ask for the missing context, so the change is built on

the file and not on memory. 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** (Output format below).

## Integration moves

Each move names, in parentheses, the tell a reviewer searches for when

the move was skipped.

- Place new behavior with its kin (tell: a function appended at the

bottom because it was the path of least resistance).

- Replace old behavior in place (tell: a wrapper, a `handleXNew`, `_v2`,

`Improved` or `Enhanced` suffix, or a boolean flag routing around the

old code).

- Change the general logic when the requirement changes it (tell: an

`if` for the new case beside general logic left untouched).

- Delete what the change made redundant (tell: dead branches, duplicated

logic, or code kept "to be safe").

- Fix the defect in the abstraction that owns it (tell: the symptom

fixed at the call site).

- Restructure when honoring the request properly needs it, and say you

did (tell: a bad structure preserved because the request didn't name

it).

- Treat known siblings of the defect as one class and land the fix once,

per the class sweep below (tell: the handed instance fixed while

siblings keep the defect, or the same edit pasted into copies that

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, because

the copy is the mechanism that produced the drift, and re-copying

runs that mechanism 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 in that member's own conventions, then **verify uniformity by

diff**, 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, because a silent partial

fix reads as a complete one.

## Scope rule

Holistic is bounded. Stay within the file or module you were given and

the **direct consequences** of the request. Flag a change before you

make it when it redesigns an unrelated subsystem, swaps a library, or

changes a public interface other code depends on. "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.

Scope bounds by relevance; the class sweep bounds by identity. A problem

unrelated to the request is filed as its own increment and fixed there.

Another instance of the defect you were sent to fix is the same work

wherever it lives, because the file boundary is not the shape of the

bug; the seam that should own the fix belongs to the sweep too, even in

a file the request did not name.

If proper integration requires touching other files, sweep territory

included, **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. These follow supersede-don't-delete

instead of this skill:

- the plan-of-record's history/changelog (see `grill-planner`: stale

claims are struck through, not deleted),

- any changelog or audit log.

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.

The two kinds meet wherever a record of a claim outlives the claim, and

such records are true-shaped: their form reads as evidence whatever

their content says, so review passes over them.

- **A dated defect note** in a test or code comment ("measured: X fails

when Y") cites its subject by symbol, so it can be found when the code

moves, and is retracted in the commit that fixes the defect. Left in

place, it goes on reading as a measurement after the defect is gone,

and the next reader cites it as a premise.

- **A recorded claim found false** gets two marks in the edit that

retracts it: the original is struck through, and a dated

**Correction** beside it states the corrected finding. This is the one

retraction rule for a graph fact (`knowledge-graph`, rule 5) and for

an archived copy kept because the reasoning error is itself the

next agent from re-deriving the mistake; the strike stops a search

that lands on the old line from reading it as a second live claim. The

current fact still has one home, and the Correction records how it got

there.

## 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.

- Before I delete something as unused, did I search for **each file by

name across the whole tree**? A "nothing uses this" verdict covers

only the consumers that were traced. "Is this entry point wired?" and

"is this file referenced?" are different questions, and a deletion

depends on the second. State the blast radius per file, not per path

or feature.

- Do all names, comments, and docs still tell the truth, including a

dated defect note this change just made false?

- 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 on 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, meaning the full file, or the

full revised functions or sections when the file is very large.

4. **Changelog**: a bullet list that *includes anything you removed or

restructured beyond the literal request*, so it can be vetoed.

Deletion and restructuring are the parts most likely to surprise, so

surface them loudest.

## Trivial changes

Genuinely trivial changes (a typo, a comment, a lint fix, a single-line

config value) take the trivial-change shortcut, with no four-part

report. 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 stays trivial only while its identifier stays inside one

process. Once 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), the rename is an

**unversioned contract** change: some other process, stored record, or

in-flight message still speaks the old name, and nothing fails at

compile time. The diff looks like a one-line rename, and that look is

how such renames silently break service-oriented and serialized-data

systems. Treat it as a contract change (versioned, migrated, or

dual-read), whatever the diff size.

## 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 tells of skipped

integration 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.