Skip to content

ByteTerrace/Puck / .claude/skills/boy-scout

boy-scout

Verified

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?

TierWhat qualifiesWhat you do
OwedStaleness 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 orphansFix it in the same change, wherever it lives, even outside the directory you started in
In passingA 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 linkFix it in the same change when it is a line or two
RecordedEverything else: a defect in another area, dead code elsewhere, a stale document you are not touching, anything whose fix would change observable behaviorLeave 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 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

QuestionSkill
Find old-name occurrences in docs, comments and configscontent-search
Find C# callers and orphans of a renamed or deleted symbolsymbol-analysis
Which checks show the change worksverification
A recorded behavior bug: the owning subsystempuck-world, puck-dsl, rendering or the area's own skill

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

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: 469kUpdated Claude CodeCodexVerifiedInstall
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: 197kUpdated Claude CodeCodexVerifiedInstall
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: 197kUpdated Claude CodeCodexUnverifiedInstall
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: 197kUpdated Claude CodeCodexVerifiedInstall