Doc sweep

Align Docs to Code

Check whether the project's "engineering content" — the human-facing material around code — still describes what the code does, and fix the drift. The code is the reference; the engineering content is checked against it.

Engineering content = code comments and docstrings; all human-authored prose docs regardless of format — README, CHANGELOG, CONTRIBUTING, SECURITY, CODE_OF_CONDUCT, docs/**, and any *.md / *.rst / *.adoc / *.org / *.tex; docs-as-code contract specs (OpenAPI/Swagger openapi.*/swagger.*, *.proto, GraphQL *.graphql/*.gql, JSON Schema); agent-instruction files (AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md, .cursorrules, .windsurfrules); and memory (.claude/.../memory, .remember).

Why this matters

Comments rot faster than code: someone renames a function, swaps an algorithm, and the comment now actively lies — worse than no comment, because the next reader trusts it. The goal is "remove false statements that mislead," not "make docs pretty."

The trap: when a comment contradicts the code, the lazy fix is to rewrite the comment to match. But sometimes the comment was right and the code is the bug — rewriting it then buries the bug under an updated lie. So this skill never blindly aligns docs to code; per finding it decides which side is wrong.

Core idea: classify every divergence before touching anything

Every discrepancy is one of four buckets; the bucket decides the action.

Type A — Behavioral drift. The doc describes behavior the code no longer matches, and the code is the deliberate, working behavior. → Edit the doc.

• Tell: surrounding code clearly works and was written this way; the doc just wasn't updated.
• Example: comment says "returns the user's email" but code returns the whole User after a refactor.

Type B — Invariant / constraint violation. The doc states a rule or contract the code breaks — words like must / always / never / required / invariant / callers must / throws if. → Do NOT touch the code. Do NOT rewrite the doc to bless the violation. Flag it as a suspected bug for a human. Invariant violations are high-value signals — silently "aligning" them hides real defects.

• Example: comment says "callers must hold the lock before calling" but the function reads shared state without acquiring it. Almost certainly a bug, not a doc problem.

Type C — Stale references. The doc points at things that moved or died: renamed symbols, removed functions, dead links, wrong file paths, wrong arg counts/signatures in examples, deprecated env vars. → Edit the doc (within scope) to point at the real thing.

Type D — Out of edit scope. The divergence is real but lives in an agent-instruction file (CLAUDE.md, AGENTS.md, GEMINI.md, .cursorrules, …) or memory. → Report only; propose the corrected text but do not write it — these are the agent's own instructions and the user's personal memory; silently rewriting them is surprising.

What you may and may not edit

• May auto-edit (after confirmation): inline code comments, docstrings, project prose docs (README, CHANGELOG, CONTRIBUTING, SECURITY, docs/**, any *.md/*.rst/*.adoc/*.org/*.tex), and contract specs (openapi.*, *.proto, *.graphql, schema files) — unless generated (see codegen caveat below).
• Report-only (propose, don't write): agent-instruction files — CLAUDE.md, AGENTS.md, GEMINI.md, .github/copilot-instructions.md, .cursorrules, .windsurfrules — and memory files.
• Never auto-edit: the code itself. Type B findings are flagged, never fixed by this skill.
• Never: commit, push, create PRs, add remotes. This skill only edits the working tree.

Docs-as-code contract specs

Machine-readable specs that describe the code's external contract drift as often as prose — treat them as engineering content too: OpenAPI/Swagger (openapi.*, swagger.*), gRPC/protobuf (*.proto), GraphQL schema (*.graphql/*.gql), JSON Schema / AsyncAPI. They're editable project files, checked after confirmation like README.

How to verify: cross-reference each declared path/endpoint/message/type/field against the real code — route handlers, struct or message definitions, enum values — then classify by the same buckets:

• Type C — the spec names an endpoint, param, field, or type that was renamed/removed/retyped in the code → edit the spec to match.
• Type B — the spec states a contract the code no longer honors (required: true but the field isn't validated; an enum value the code never produces) → flag as a suspected bug; don't bless it by editing the spec.

Codegen caveat: if the spec is generated from code/annotations or a build step (not hand-maintained), do not hand-edit it — the generator or its source annotations are the real source of truth; flag those instead.

The workflow

1. Discover — map both sides

Use your own tools (Glob, Grep, Bash, Read) to inventory the project — adapt to whatever layout you actually find. Gather both sides: the engineering content to check and the source code it must match.

• Honor .gitignore so build output, venvs, and caches don't drown the signal. In a git repo: git ls-files --cached --others --exclude-standard. In a non-git dir, just skip obvious vendored/build trees as you Glob.
• Memory is the exception: .claude/.../memory and .remember are frequently gitignored yet always in-scope — find them explicitly.
• Scope is judgment, not a filter: comments/docstrings/prose docs (*.md / *.rst / *.adoc / …) are editable; agent-instruction files and memory are report-only.
• Contract specs too: also pick up *.proto, openapi.*/swagger.*, *.graphql/*.gql, and schema files — they're in-scope engineering content (see "Docs-as-code contract specs").

For a large repo (>~30 files of interest), dispatch parallel Explore subagents — one per top-level directory/subsystem — each returning a structured list of (doc claim, code reality, location) triples. Don't read everything serially.

2. Analyze & classify — one finding per discrepancy

For each claim touching behavior, signatures, types, side effects, error cases, or external contracts, verify it against the code. Classify A/B/C/D. Record file:line, what the doc says, what the code does, classification, and proposed fix.

3. Report — present before changing anything

Output one report using the template below, grouped by type. Every finding is concrete and citeable (file:line). Separate "will fix" (in-scope A/C) from "needs your call" (B, suspected bug) and "propose only" (D).

4. Confirm

Ask which findings to apply. Default: apply all in-scope Type A and C; do not apply B or D. Let the user veto individual rows or add scope.

5. Apply — batch, then verify

Apply confirmed edits with Edit — minimal, faithful changes, preserving the original tone and language. Do not commit. Re-read the changed regions to confirm they read correctly.

6. Verify & hand off

Re-check the touched claims against the code. Summarize: N fixed, M flagged as suspected bugs (list each invariant violated), K proposed for manual CLAUDE.md / memory edit. On main/master, remind the user to create a feature branch before committing — but do not branch or commit yourself.

Editing guardrails (non-negotiable)

• Never commit, push, add remotes, or open PRs. Output = working-tree edits + a report.
• Branch awareness only: on main/master, remind the user to branch before committing; do not branch or commit yourself. Non-git dir: skip.
• Scope: code comments, docstrings, and project prose docs (*.md / *.rst / *.adoc / *.org / *.tex — README, CHANGELOG, CONTRIBUTING, docs/**, …) only. Not agent-instruction files (CLAUDE.md / AGENTS.md / GEMINI.md / .cursorrules), not memory, not code.
• Faithful edits: rewrite the false sentence to be true; don't delete useful context or invent details you didn't verify against the code.
• No fabrication: if a claim can't be verified against the code within a reasonable search, mark it "unverified" — never edit an unverified claim.

Report template

# Doc-Code Alignment Report

## Summary
- Scope: <dirs/files>
- Doc files: <count>  |  Code files: <count>
- Will fix (A/C): X   |   Suspected bug (B): Y   |   Propose only (D): Z

## Will fix — batch-apply (A/C)
| Location | Doc/comment says | Code actually | Type | Proposed fix |
|----------|-----------------|---------------|------|--------------|
| src/auth.ts:42 | "returns email" | returns User object | A | change to "returns User object" |

## Suspected bug — code NOT changed, your call (B)
| Location | Stated invariant | Actual code violation |
|----------|------------------|-----------------------|
| src/cache.rs:88 | "callers must hold the lock" | reads shared state without acquiring it |

## Propose only — edit CLAUDE.md / AGENTS.md / memory by hand (D)
- CLAUDE.md:7 — says "use pnpm" but repo is an npm project; propose "npm"

When to parallelize

For small repos (~≤30 files of interest), do it inline. Above that, dispatch parallel Explore subagents (one per subsystem) to gather findings, then classify and dedupe in the main thread. Classification and the final report always happen in one place so the A/B/C/D buckets are applied consistently — never let a subagent decide, on its own, to rewrite a comment that actually hides a bug.