derot — truth-drift auditor
Rot = any place a repo's stated intent has drifted from what the code/build actually is. derot finds it, verifies it against ground truth, and fixes it — correcting where the knowledge is still useful, deleting only what is purely obsolete.
The five rot dimensions
- Comment rot — comments that lie about the code beneath them: stale version numbers, references to renamed/removed symbols/methods/files/diagnostic-IDs, resolved
TODO/FIXME/HACK/"temporary"/"workaround for X", descriptions of old behavior, copy-paste comments describing a different member, dead-code comments.
- Doc rot —
CLAUDE.md / README / CHANGELOG / workflow tables whose dependency versions, file lists, command names, or workflow names don't match reality. (Shipped past CHANGELOG entries are history, not rot — never flag them.)
- Infra rot — workflow comments that lie; unpinned actions (
@v1 → SHA-pin with a # vN comment); hardcoded publish accounts → dynamic secrets; expired/long-lived API keys → OIDC trusted publishing.
- Version sync — pins/claims out of sync across
Version.props / Directory.Packages.props / global.json / docs; published-vs-pinned drift; a property referenced but defined only by an injected SDK (annotate, don't "fix").
- Dependency rationalization — a narrow sub-package used where a parent/meta suffices; a superseded package still used after its successor shipped; redundant direct references already present transitively. This dimension needs external knowledge, not just the repo — see
references/dependency-rationalization.md.
Discipline — non-negotiable
- Correct beats delete. If a comment explains a genuinely non-obvious why (a workaround's reason, an invariant), fix the wrong details and KEEP the explanation. Delete only when purely obsolete.
- Verify root + every transitive use. Before changing anything a comment/doc describes, read the code it refers to and everything that depends on it. Never "fix" a comment to match a wrong assumption — fix whichever of {comment, code} is actually wrong, and chase the change through every caller.
- Never invent. Can't confirm it's stale? Leave it; report it as
unverified. Do not guess.
- Terse + behavioral corrections. Say what/why; don't restate the code.
- No drive-by behavior changes. Comments/docs + the named CI modernizations only — unless fixing rot exposes a real bug, in which case say so and fix the root cause.
Verification recipes (how a candidate becomes a confirmed finding)
- Version claim → read
Version.props / Directory.Packages.props / global.json, and the injected SDK props if a property is undefined locally; confirm the actual resolved value before calling a number stale.
- Names a symbol / file / diagnostic ID / method / workflow →
grep / ls to confirm it still exists and is spelled right.
- Describes behavior → read the code directly under/around the comment and confirm they agree.
- Dependency choice → see the references file: the NuGet graph for transitive-already-present + true subset; cited vendor docs /
nuget-opensrc / microsoft-docs for succession.
Classify each candidate: confirmed-rot (wrong → fix/delete) · correct-keep-explanation (details wrong, why valid → corrected text that keeps the explanation) · obsolete-delete (purely obsolete → delete) · unverified (cannot confirm → leave + report).
Running a pass
Small scope: inline — scan → verify → fix → build → report.
Large repo: fan out rot-scout agents (read-only, one per area — they parallelise cleanly) and a dep-analyst for dimension 5; synthesize their verified findings into one apply-list; then YOU apply the edits, build/test, and commit. A Workflow is ideal for many areas. The orchestrator — not the scouts — performs the mutations, so comment removal stays under one reviewer's control.
Always finish with: build/test evidence (exact commands + results), a per-change root-cause summary, and a flagged, not changed list (secrets to delete, unverified candidates, dependency calls needing a human decision). derot proposes; the human disposes — especially for dependency swaps, which change the build.
1---2name: derot3description: Truth-drift auditor — find & fix comment/doc/CI/version/dependency rot that contradicts the current code, with root + transitive verification (correct beats delete). Use when the user wants to remove stale comments, fix doc drift (CLAUDE.md/README/CHANGELOG), modernize CI publish auth, sync package versions, or question why a sub-library is used instead of a parent/successor package. Triggers on "stale comments", "derot", "doc rot", "comments are out of date", "docs don't match the code", "clean up the docs", "why this dependency", "überarbeitung".4---56# derot — truth-drift auditor78**Rot** = any place a repo's *stated* intent has drifted from what the code/build *actually* is. derot finds it, verifies it against ground truth, and fixes it — correcting where the knowledge is still useful, deleting only what is purely obsolete.910## The five rot dimensions11121. **Comment rot** — comments that lie about the code beneath them: stale version numbers, references to renamed/removed symbols/methods/files/diagnostic-IDs, resolved `TODO`/`FIXME`/`HACK`/"temporary"/"workaround for X", descriptions of old behavior, copy-paste comments describing a different member, dead-code comments.132. **Doc rot** — `CLAUDE.md` / `README` / `CHANGELOG` / workflow tables whose dependency versions, file lists, command names, or workflow names don't match reality. (Shipped past `CHANGELOG` entries are history, not rot — never flag them.)143. **Infra rot** — workflow comments that lie; unpinned actions (`@v1` → SHA-pin with a `# vN` comment); hardcoded publish accounts → dynamic secrets; expired/long-lived API keys → OIDC trusted publishing.154. **Version sync** — pins/claims out of sync across `Version.props` / `Directory.Packages.props` / `global.json` / docs; published-vs-pinned drift; a property referenced but defined only by an injected SDK (annotate, don't "fix").165. **Dependency rationalization** — a narrow sub-package used where a parent/meta suffices; a **superseded** package still used after its successor shipped; redundant direct references already present transitively. This dimension needs external knowledge, not just the repo — see `references/dependency-rationalization.md`.1718## Discipline — non-negotiable19201. **Correct beats delete.** If a comment explains a genuinely non-obvious *why* (a workaround's reason, an invariant), fix the wrong details and KEEP the explanation. Delete only when purely obsolete.212. **Verify root + every transitive use.** Before changing anything a comment/doc describes, read the code it refers to and everything that depends on it. Never "fix" a comment to match a wrong assumption — fix whichever of {comment, code} is actually wrong, and chase the change through every caller.223. **Never invent.** Can't confirm it's stale? Leave it; report it as `unverified`. Do not guess.234. **Terse + behavioral corrections.** Say what/why; don't restate the code.245. **No drive-by behavior changes.** Comments/docs + the named CI modernizations only — unless fixing rot exposes a real bug, in which case say so and fix the root cause.2526## Verification recipes (how a candidate becomes a confirmed finding)2728- **Version claim** → read `Version.props` / `Directory.Packages.props` / `global.json`, and the injected SDK props if a property is undefined locally; confirm the actual resolved value before calling a number stale.29- **Names a symbol / file / diagnostic ID / method / workflow** → `grep` / `ls` to confirm it still exists and is spelled right.30- **Describes behavior** → read the code directly under/around the comment and confirm they agree.31- **Dependency choice** → see the references file: the NuGet graph for transitive-already-present + true subset; cited vendor docs / `nuget-opensrc` / `microsoft-docs` for succession.3233Classify each candidate: `confirmed-rot` (wrong → fix/delete) · `correct-keep-explanation` (details wrong, *why* valid → corrected text that keeps the explanation) · `obsolete-delete` (purely obsolete → delete) · `unverified` (cannot confirm → leave + report).3435## Running a pass3637**Small scope:** inline — scan → verify → fix → build → report.3839**Large repo:** fan out **`rot-scout`** agents (read-only, one per area — they parallelise cleanly) and a **`dep-analyst`** for dimension 5; synthesize their verified findings into one apply-list; then YOU apply the edits, build/test, and commit. A Workflow is ideal for many areas. The orchestrator — not the scouts — performs the mutations, so comment removal stays under one reviewer's control.4041Always finish with: build/test evidence (exact commands + results), a per-change root-cause summary, and a **flagged, not changed** list (secrets to delete, unverified candidates, dependency calls needing a human decision). derot proposes; the human disposes — especially for dependency swaps, which change the build.
ANcpLua