cleanup-repo

A Claude skill for pruning unneeded docs/code and normalizing documentation style in a repository — safely, on a branch, with every destructive or lossy change traced to a fact before it happens.

What it does

cleanup-repo covers two distinct operations that share one discipline:

• Prune — removes what the repo doesn't need: stale planning docs, committed junk (build output, .DS_Store, binary store files), and genuinely dead code.
• Restyle — rewrites documentation prose to a target writing style (e.g. ASD-STE100 Simplified Technical English) at scale, across many files, without touching code blocks, data, or other verbatim content.

If a request names neither operation, or the scope is ambiguous ("clean this up"), the skill asks which is wanted rather than guessing. When both are wanted, prune runs first — fewer files left to restyle.

Shared discipline

Both operations follow the same four rules:

1. Branch first. Work happens on chore/cleanup-<what>, never on the default branch.
2. Batch and checkpoint-commit. Each folder or category is committed as it finishes, so a half-finished session still leaves clean, reviewable history — not one giant diff.
3. Trace before you touch. Nothing is deleted and no prose is changed until it's been confirmed. The verification method differs by category, but the rule never bends.
4. Report held-back items. Anything uncertain is listed for the user and left in place. Guessing is treated as the failure mode, not caution.

Prune

Removes stale docs, committed junk, and dead code, each verified differently:

Category	What it looks like	How it's verified
Stale planning docs	Delegation plans, brainstorms, completed refactor RFCs	Grep the repo for references from live docs (specs, ADRs, README, code)
Committed junk	.pnpm-store/*.db, .DS_Store, build output, editor lock files	Confirm machine-generated, then git rm --cached + add to .gitignore in the same commit
Dead code	Flagged by knip, ts-prune, or depcheck	Every finding is individually verified — most flags are false positives

ADRs, current specs, and API docs are kept even when superseded, since they record decisions and history; a superseded doc kept for inbound links gets a banner instead of a delete.

A dead-code tool's flag is treated as a hypothesis, not a verdict. Before deleting anything it flags, the skill greps the whole repo for the file's basename and checks for zero live references. Common false positives it watches for: migration/CLI scripts exercised only by a test or cited only in docs, workflow/data files read by a config the tool never parses, files named in code comments, exports that are locally used even though "unused" by the tool, and dynamically-loaded runtime or test/build dependencies. Completion means every flagged item is either traced to zero references and deleted, or kept with a one-line reason — and if a whole tool run turns up nothing safe to delete, that's reported as a real result rather than forced.

Restyle

Rewrites doc prose to a target style at scale:

1. Get the target style as an input — fetched from a named skill/doc, or stated by the user. Any project glossary (e.g. CONTEXT.md) is read first so canonical terms are used correctly.
2. Inventory and batch — every target doc is sized with wc -l, then ordered lowest-risk first (README, glossary) through specs to ADRs and research notes, one commit per folder.
3. Rewrite prose to the style, while preserving verbatim: code blocks, JSON, table data, wire shapes, identifiers, §/ADR/issue references, markdown links, and frontmatter.
4. Leave data artifacts unchanged — generated output samples, changelogs, and captured logs are evidence of what a run produced, so restyling them would falsify the record. These are skipped, with the reason noted in the commit.

Completion means every doc in the inventory is either rewritten or explicitly left verbatim with its reason recorded.

When it stops and asks

• The request doesn't name an operation, or the scope is ambiguous.
• A deletion candidate is recent, referenced live, or a decision record.
• No target style is specified and no source document names one.

Usage

This skill has disable-model-invocation: true, meaning it must be invoked explicitly (e.g. /cleanup-repo) rather than triggered automatically by Claude noticing a matching request.