/sdlc:docs-sweep

Make a codebase's comments true. Shorter is a side effect, not the goal.

Usage:

• /sdlc:docs-sweep — sweep the whole project.
• /sdlc:docs-sweep packages/ts solutions/determined — restrict to those paths.
• /sdlc:docs-sweep --report-only — find and report; write nothing.

The rules that govern everything

Accuracy is the goal; brevity is a side effect. A wrong comment costs more
than a verbose one. Never set a line-reduction target — measured against a real
corpus, roughly 80% of comment lines are load-bearing, and a sweep that promises
a big number buys it by deleting knowledge.

When unsure, keep. A wrongly-kept line costs a line. A wrongly-deleted
constraint costs an outage.

Declining is a result. A file read and left alone is a successful outcome
and gets reported as one. On a real run, 2,347 files were read and unchanged,
and four whole shards declined every block they were given.

One owner per file. Two agents editing one file lose one agent's work
silently. sdlc project scan comments enforces this; never re-shard by hand.

The session orchestrates. Scanning, editing and verification happen in
subagents. What returns here is a structured summary.

1. Scope the sweep and agree the exclusions

Confirm the tree is clean before writing anything:

git status --porcelain

Then decide what is out of scope, and say why for each. These earn exclusion:

• Frozen records — closed tasks, decision records, executed plans. Editing
  a historical document to read better falsifies it.
• Deliberately-malformed fixtures — lint corpora, golden files, snapshots.
  Formatting them destroys the test.
• Generated trees and vendored code — regenerated on the next build.
• Gate-pinned prose — any file whose exact bytes a gate asserts. Find them
  before you start; a sweep that trips a gate on commit has wasted its run.

Present the exclusion list and get agreement before scanning.

2. Scan and shard deterministically

${CLAUDE_PLUGIN_ROOT}/cli/sdlc project scan comments --output json \
  --path <scope> --exclude '<regex>' > .sweep/manifest.json

The op nominates runs of >= 4 comment lines carrying no signature annotation
and no tooling directive, drops generated files by their banner, drops tracked
symlinks, bands each file, and shards one owner per file. It fails loudly if
sharding is not disjoint.

Read totals and the shard table back to the user. If totals.lines is under
a few thousand, do the work inline — a workflow costs more than it saves.

3. Sweep, one agent per shard

Dispatch the sweep workflow with the shard list:

Workflow({
  scriptPath: "${CLAUDE_PLUGIN_ROOT}/skills/docs-sweep/sweep.workflow.js",
  args: { shards: [ … ], rubric: "<the rubric below, verbatim>" }
})

Every agent gets the rubric verbatim. It is the whole judgement of the
sweep, and paraphrasing it is how a sweep goes wrong.

The rubric

Delete:

• Restatement of the adjacent code.
• History narrative — "formerly", "used to", "moved from", bare PR-number
  provenance. Git holds this.
• Design rationale of the "why this mechanism and not that one" form; that
  belongs in a decision record.
• A second copy of prose that exists elsewhere. Verify the survivor first.

Keep — never delete, tighten at most:

• A constraint, contract, or invariant the code does not itself state.
• A gotcha, or why the obvious alternative fails.
• A cross-file coupling ("this must match X or the codegen gate fires").
• A measured fact — a perf number, a limit, a pinned version and its reason.
• A statement about EXTERNAL behaviour: an upstream bug, an OS quirk. The code
  cannot restate it and git does not carry it.

Tighten: the same fact in fewer words.

The trap that catches every sweep

"Drop history narrative" is right when the history is provenance and wrong
when the history IS the fact. On a real run this single misfire produced
false comments in eight modules:

Every body moved VERBATIM out of api/v1/backup.rs — true —
became is a VERBATIM copy of the one in api/v1/backup.rs — false.

The bodies moved; that file now holds one-line dispatches. The rewrite asserted
a duplicate implementation that does not exist. Before deleting a past tense,
check what present tense you are leaving behind.

Never touch

• Anything inside a compiled doc-test fence. In Rust only bare and no_run
  fences compile; text and ignore are inert.
• A signature annotation on an exported symbol in a package that publishes API
  docs — deleting it or breaking a {@link} emits a build warning.
• A directive comment, or its position relative to the line below it.
• A transcluded block whose bytes a generator copies verbatim.
• A runtime string. A tool description, an error message, a CLI help line is
  not a comment; editing it changes behaviour. This one has slipped through
  twice — check what the string is FOR, not where it sits.

4. Verify — three passes, not one

Verification is most of this skill's value. Run all three.

4a. The comment-only gate. Mechanical, cheap, and it catches what nothing
else does:

${CLAUDE_PLUGIN_ROOT}/cli/sdlc gate comment-only

Every line removed from a source file must be a comment. Do not pipe this
command; a pipeline returns the last stage's exit code and the gate stops
gating. A violation means an agent deleted code — find it before anything else.

4b. Review the removals that lost something. Do not re-read all removals;
most were rewrites and reading them reads the same fact twice. Filter to
removals that carry a constraint, prohibition, failure mode, coupling or
measured number AND whose distinctive wording did not survive into the
replacement. On a real run that narrowed 12,215 removed lines to 642 — a 19x
smaller target, on which agents confirmed 610 correct removals and restored 32.

4c. Check that what the sweep WROTE is true. The pass every sweep skips.
Passes 4a and 4b both ask "was something lost?"; neither asks "is the
replacement correct?" On a real run 26 of 277 added assertions were false —
9.4%. Take the added lines that assert something checkable — a path, a decision
id, a count, a "must/never/only", a claim about a return value — and verify each
against the code. A confidently-wrong comment is worse than the verbose one it
replaced.

Then run the project's own quality checks. A comment-only change that breaks a
build means the sweep touched something load-bearing.

5. Report what did not change

Commit in area groups so a large diff stays reviewable by ownership, then
report:

• Claims corrected, with what was claimed and what was actually true.
• Files read and deliberately left alone.
• False positives spared — flags a script raised that agents refused to act on.
• Anything declined with its reason.

The decline count and the spared-false-positive count are evidence the sweep
exercised judgement. Report them as prominently as the reductions.

Terminal marker on success:

DOCS-SWEEP-DONE files=<n> removed=<n> added=<n> corrected=<n> declined=<n>

On a blocking failure, ERROR reason="...".

Notes

• Skill-authoring conventions. See ${CLAUDE_PLUGIN_ROOT}/skills/CLAUDE.md —
  this skill's terminal markers are namespaced DOCS-SWEEP- for the reason
  documented there.
• Deterministic over LLM. The scan, the sharding and the comment-only gate
  are ops precisely because they are mechanical; per P-0001-prefer-deterministic-over-llm
  only the rubric needs judgement.
• Not this skill. Formatting is a linter's job; finding defects is
  /sdlc:bug-finder.