Sweep documentation drift after a change

Sweep every documentation claim for drift immediately after a change, while the diff that caused it is still legible.

Also usesclaude-plugins-official

Docs drift is asymmetric: the code moves and the prose does not, so the drift is always in the same direction and is never announced. The cheapest catch is a claim-level sweep immediately after the change, while the diff is still legible.

Start here

One prompt to start

We changed several things this week -- sweep the documentation for drift against the current code right now, while the diff is still legible, check the comments in the same touched files for the same kind of rot, and only once the docs are accurate, survey how the surrounding conventions are actually written.

Needsself-assess, pr-review-toolkit, codebase-consistency

Beats

Run these in order. Each prompt is copy-pasteable straight into Claude Code.

1. self-assess:self-assess-docs-driftalso in 2 other recipes

   • Check cross-forge CI parity
   • Improve a stale CLAUDE.md without trusting its own claims

   Verifies every extracted, in-scope claim against the current codebase; run months later it produces a backlog instead of a fix.

   Run this beat on its own

   we renamed several things this week — check whether the docs still describe what the code actually does

2. pr-review-toolkit:comment-analyzeralso in 1 other recipe

   • Fix misleading error or diagnostic output

   Comments drift from the same edit as docs, and no docs sweep reads them.

   Run this beat on its own

   check the comments in the files this change touched — are any of them now describing behavior that moved?

3. codebase-consistency:pattern-analyst

   Genuinely post-hoc; a convention survey run before the content is correct clusters variants of the wrong text.

   Run this beat on its own

   now that the docs are accurate, survey how docstrings are actually written across this repo and cluster the variants

Worked example

Grounded in — why this beat order is trustworthy

this repo generates part of its own documentation surface: `.rrt.toml` declares `[[tool.rrt.docs.shared_blocks]]`, which is what regenerates the `rrt:auto:start:example-prompts-intro` block visible at the top of every plugin README's Example Prompts section — so a drift sweep must distinguish generated prose from hand-written prose before reporting either.

Do / Don't

• ✓Sweep documentation for drift immediately after a change, while the diff that caused it is still legible.
• ✓Check comments in the touched files for the same kind of drift -- no docs sweep reads them on its own.
• ✓Run any convention survey only once the docs are already accurate -- done earlier, it clusters variants of the wrong text.
• ✓Distinguish generated prose (like the shared Example Prompts block) from hand-written prose before reporting either as drifted.

• ×Don't wait to sweep for docs drift -- done months later it produces a backlog instead of a fix.
• ×Don't assume a docs sweep also covers comments -- it doesn't, and they drift from the same edit.
• ×Don't survey conventions before the docs content is corrected -- it will cluster variants of text that's already wrong.
• ×Don't flag a generated block (like the shared Example Prompts intro) as hand-authored drift without checking whether it's regenerated by tooling.