Boy Scout

---
name: boy-scout
description: "Scopes cleanup when finishing a Puck change: stale citations, links, comments and docs after a rename or move, typos, unrelated bugs found, formatter sweeps. Owed, in-passing or recorded."
---

# 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](../../../docs/development/documentation.md) owns prose,
titles, filenames, README ownership and navigation.