kenryu42/code-scans/maintain-code-scans-skill

Maintain a code-scans skill

A code-scans skill rots the moment the tree is refactored. It keeps naming retired directories, its enumerations lose members, it cites a gate that was removed, and it misses the contract corpus that AGENTS.md started protecting last month. A surveying agent that trusts it then searches the wrong roots and proposes deleting something settled. This skill is the upkeep loop for a skill generated by /create-code-scans-skill (or any project-local simplification-survey skill of the same shape). The unit of rigor is the claim: every path, every protected-surface entry, every corpus rule, every command the skill names either still holds or gets fixed.

Outcomes

Pick one, and say which:

• clean — every claim was checked, the live pass ran, nothing worth shipping. No branch, no PR.
• changed — one PR ships proven corrections to the skill.
• blocked — a check could not finish or a proven fix could not ship safely. Say exactly what blocked it.

Edit scope

Only edit the code-scans skill's own directory. Never edit product code, docs, or notes to make the repo match the skill: when they disagree, the repo is the truth and the skill is what changes. Simplification candidates the live pass turns up are a by-product: report them to the user in the shape the skill prescribes, but keep them out of this PR.

Pass

1. Locate the target. Find .agents/skills/code-scans-*/SKILL.md (with .claude/skills/code-scans-* symlinks pointing to the same directories). If none matches, look for an older project-local skill with the same shape (survey domains, corpus classification, prove-or-reject rules; often named *-find-simplifications) and confirm it with the user. Several candidates → ask which one; none → stop and point at /create-code-scans-skill instead of inventing a target.

1. Path audit. Run scripts/check-skill-paths.sh <SKILL.md> from this skill's directory. For each MISSING line, decide which it is: renamed (find the successor with git log --follow, git log --diff-filter=R, or rg for the symbols it held, then update the path) or gone (delete the claim that depended on it, not just the path; a survey domain whose root no longer exists is not a domain). untracked lines are fine only for generated output the skill tells the reader to ignore. Also open every relative Markdown link the skill makes. A false positive (an event-name prefix, a module specifier, or a verbatim quotation that looks like a path) is named in the report, not "fixed".

1. Doctrine diff. Take the skill's last commit as the base and run git diff <base>..HEAD --stat over every doctrine file, doc, notes tree, and contract corpus the skill cites, then read the additions: a new section in a cited doc (an implementation-status inventory, a new protected data class) is drift the skill must absorb, and a re-read alone tends to miss it because the old text still reads true. Then re-read what the generator interviewed: AGENTS.md, CLAUDE.md, CONTRIBUTING.md, REVIEW.md, SECURITY.md, the docs the skill tells its reader to read, the notes or ADR tree and its rules, and the contract corpora and snapshot surfaces. Then re-verify every quotation and attribution the skill makes at its cited location, including ones the diff says did not change: a quote can be wrong from the day it was written, and a rule the skill attributes to one doc often lives in another. Compare against the skill's intentional-by-default list, corpus classification, trust boundary, dependency posture, deliverable channel, and validation commands. A protected surface the repo now documents but the skill omits → add it with its citation. A protected surface the skill lists but the repo has retired or deliberately removed → delete it. A changed check command, gate, or base branch → update it.

1. Churn sweep. Take git log --stat since the last commit that touched the skill, restricted to the production roots the skill names. Look for new, renamed, or removed top-level directories and packages (survey domains), new trees that hold source or test files outside the production roots (prototype code inside a docs tree belongs in the ambiguous corpus), removed or added dependencies and tools (any guidance that names them), renamed terminology (naming-contract refactors), and retired features the skill still describes as surveyable. Require a concrete current path before adding a domain, and a concrete removal commit before deleting one.

1. Enumeration audit. For every list of concrete things in the skill (hosts, packages, files, tools, people, machine paths), ask whether membership changes over time. If it does, replace the list with the rule that generates it ("every directory under src/hosts", "whatever git ls-files does not list", git rev-parse --show-toplevel). This is the failure mode the history of these skills shows most often, and it is cheaper to fix than to re-fix every quarter.

1. Live pass. Required even when the text looks clean, because text can be internally consistent and still teach wrong searches. Follow the skill's own instructions for one survey domain, rotating the domain between runs and noting which in the run notes. Prove or reject at least two candidates end to end using only the skill's corpus classification and search recipes, and produce the deliverable in the skill's prescribed shape in a scratch location. Drift shows up as: a search recipe that finds nothing because a naming convention changed; a corpus rule that misclassifies a real consumer; a candidate the skill's rules call strong that the repo protects somewhere the skill does not cite; a deliverable instruction that cannot be followed because the notes directory moved or the report format changed; a validation command that no longer exists. Each is drift: fix it under edit scope and retry that step once before calling the pass blocked.

1. Triage. Wrong or missing claim → drift, fix it. Guidance that is generic filler and demonstrably not pulling its weight → may be trimmed, keeping the skill lean; do not rewrite tone or restructure sections that are still accurate. Product behavior that looks broken → report it to the user, keep it out of this PR. Genuine simplification candidates from the live pass → report them, keep them out of this PR.

1. Ship or stop. For changed: rerun the path checker (zero MISSING), re-read every changed file cold, and open one PR whose message names what rotted and why, following the repo's commit conventions and running whatever the skill's own Validation section says a docs-only change needs. For clean or blocked: no PR; report the outcome, the claims checked, the domain driven live, and any candidates or product gaps found.

Keep concise run notes (claims checked, drift confirmed, domain driven, candidates found, outcome) in a scratch location; do not commit them.