# Derot

> 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".

- Skill: `ancplua/derot` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add ancplua/derot`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ancplua/derot/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ANcpLua (https://skillmd.com/u/ancplua)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/ancplua/derot

---


# 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

1. **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.
2. **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.)
3. **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.
4. **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").
5. **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

1. **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.
2. **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.
3. **Never invent.** Can't confirm it's stale? Leave it; report it as `unverified`. Do not guess.
4. **Terse + behavioral corrections.** Say what/why; don't restate the code.
5. **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.