stale
Skill0 starsChanged 2 months agoMITView on GitHub
Detect documentation drift — implementation changed but documentation did not, documentation changed but implementation did not, machine contracts ahead of their derived docs, and semantic staleness. Use for "are my docs still true", before a release, or after a large change.
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 25
Run docgov inspect stale --json for review packets: each finding comes with the relevant diff hunks and the document excerpt, so you read …
- Distinctive: line 42
If a finding carries invariants, check them specifically: an invariant the code now violates is a higher-severity problem than a stale …
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Detect documentation drift
Deterministic drift report
!docgov stale --json --compact $ARGUMENTS 2>&1 | head -c 14000
What this report is, and is not
The findings above are facts: a document claims to describe code that changed while the document did not, or a specification changed with no corresponding implementation change. Those are decided from the diff and the graph.
What the report does not claim is that the prose actually contradicts the new code. That is your job, and it needs the diff.
Confirm each finding
Run docgov inspect stale --json for review packets: each finding comes with the relevant
diff hunks and the document excerpt, so you read kilobytes instead of the repository.
For each packet decide one of three things and say which:
- Real drift. The document states something the code no longer does. Quote the
document's claim and the code that contradicts it, then make the edit. Be specific —
"the document says the offline grace period is 7 days;
validator.ts:42now uses 30" is actionable, "the licensing docs look stale" is not. - Not drift. The code changed in a way the document does not speak to. Say so in one line and move on. Most findings are this, and saying so quickly is the valuable part.
- Reverse drift. The document is right and the code is wrong — the specification was updated and the implementation never followed. This is the more dangerous direction, because the code ships. Flag it as an implementation gap, not a documentation task.
Invariants
If a finding carries invariants, check them specifically: an invariant the code now violates is a higher-severity problem than a stale sentence, and it is the one thing here that can be objectively wrong.
Staleness
The staleness array scores risk from what changed around a document, not from its age.
A document untouched for two years with no implementation churn is not stale. Only report
entries whose signals you can explain.
If a finding is wrong
docgov ignore DRIFT-xxxxx --reason "..." [--expires YYYY-MM-DD]. It stays visible in
every report. Suppress the finding, never the rule.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.