ByteTerrace/Puck / .claude/skills/boy-scout
boy-scout
VerifiedScopes 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.
Two kinds of finding are exceptions to the recorded tier:
- Duplicate code, by AGENTS.md's vigilance against duplication: a second implementation, copied logic or parallel helper you read or touch is refactored to one in the same change, with every caller fixed. Only a duplicate too large for the change is recorded, in the refactoring packet with its file and line, and it is dispatched in the next wave. "Code first, verification after" defers verification, never this.
- An engine gap, by AGENTS.md's probe rule: a limit of the engine that your work had to sculpt or tune around (detail the bake cannot hold, lighting no author value controls). It is never only recorded. Fix it when it is in your scope; otherwise stop working around it, hand it back with its evidence, and say that it goes to the front of its owning plan's order, so the lead puts it there in the same landing.
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 referencedocs/reference/cli.mdfor a verb); - docfx inputs under
docs/api/(landing, navigation, configuration); the generated pagesdocs/api/api/anddocs/api/_site/are git-ignored build output ofpuck docs build, never edited by hand; - agent material: the owning skill, its references or evals,
AGENTS.md; - authored
.pucksources 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 citationschecks the console-verb tokens that skills and XML docs cite; it builds and bootsPuck.Worldunless 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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 469k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 197k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |