Boy scout

A change leaves every file it passes through at least as correct as it found it, without growing beyond what a reviewer can still see as one change. This is a restraint on scope, not permission to manufacture cleanup work, commits or artifacts. The user's current instruction outranks this file.

Three tiers, decided by one question

For each thing you notice that your change did not set out to address, ask: did my change create it, reveal it, or merely walk past it?

Tier	What qualifies	What you do
Owed	Staleness your change creates or reveals: a line citation your insertion moved, a doc, skill, comment or test that states the behavior you changed, a link or anchor your rename breaks, a name your deletion orphans	Fix it in the same change, wherever it lives, even outside the directory you started in
In passing	A small wrongness in a file you are already editing whose fix changes no behavior: a typo in prose you touch, a comment contradicted by the line beside it, a dead link	Fix it in the same change when it is a line or two
Recorded	Everything else: a defect in another area, dead code elsewhere, a stale document you are not touching, anything whose fix would change observable behavior	Leave it, and record it in the final report with its file and line

The test is ownership, not effort: a one-line fix to a file outside your change is still recorded, not fixed. A finding recorded nowhere was dropped, not left.

Every code change owns a documentation audit

Before calling a code change done, state its contract delta (names, behavior, inputs, outputs, errors, units, layouts, commands, configuration, procedures) and search for every surface that teaches it, beyond the edited directory, by the old and new names (or the existing symbol/concept when no name changes) (puck search -M 0 -l, see content-search; for a C# symbol, puck references, see symbol-analysis):

• XML API documentation on the changed members;
• inline comments stating an invariant, layout, unit or cross-language pair;
• READMEs and docs/ (the CLI reference docs/reference/cli.md for a verb);
• docfx inputs under docs/api/ (landing, navigation, configuration); the generated pages docs/api/api/ and docs/api/_site/ are git-ignored build output of puck docs build, never edited by hand;
• agent material: the owning skill, its references or evals, AGENTS.md;
• authored .puck sources and consumers that compile them. The owner rules cartridge JSON twins out of source control; remove reliance on a saved copy and check fresh compilation and semantic round trips.
• Report any surface you could not synchronize, including a file another lane owns.

Update the authoritative home and let other surfaces link to it. A behavior-preserving private refactor can finish the audit with no documentation diff; do not touch nearby docs to show you looked, and keep no persistent checklist.

What a fix owes

• An owed or in-passing fix rides the primary change's verification: a doc fix its link check (puck docs links, which also checks heading anchors and backticked file names), an XML comment the build, a code fix a build and a run. puck docs citations checks the console-verb tokens that skills and XML docs cite; it builds and boots Puck.World unless given --enumeration.
• A fix that changes observable behavior is never incidental. Exception types, return values, accepted inputs and formatted output are their own change. When a comment and the code disagree, correct the comment to the code only if the code's current behavior is the contract; otherwise report the discrepancy and route the behavior fix to its owner as a separate change.
• Every fact you remove keeps a home or is recorded stale. Before deleting or moving text, check that each claim it makes still lives somewhere true; search for incoming links and anchors to what you moved.
• A documentation-only task does not authorize code changes, and nothing here authorizes a commit the user did not ask for.

Boundaries

• Never clean another session's uncommitted files; report a problem in them. Stage explicit paths so a bulk add cannot sweep them into your commit.
• Machine-written artifacts (generated schemas, API pages, ISA headers) are regenerated by their verb, never edited.
• A text-search hit that merely contains a string is not a license to edit it.
• A formatting sweep is its own change. Format touched files with puck format --file-list <json>, a JSON array of paths.
• Before any fix outside the owed tier, ask: would the reviewer of the primary change wonder why this edit is here? If yes, record it instead.

Related skills

Question	Skill
Find old-name occurrences in docs, comments and configs	content-search
Find C# callers and orphans of a renamed or deleted symbol	symbol-analysis
Which checks show the change works	verification
A recorded behavior bug: the owning subsystem	puck-world, puck-dsl, rendering or the area's own skill

Writing documentation owns prose, titles, filenames, README ownership and navigation.