agentleFS
Sign inStart free
TheCollieryTheColliery/CoalLedger/skills/doc-rot/SKILL.md

doc-rot

Skill2 starsChanged 6 days agoApache-2.0View on GitHub

Docs-health staleness scan—content that time has made false: version strings older than the shipped version, dates and "last updated" stamps long past, stale badges, dead TODO/FIXME/"coming soon" markers, superseded instructions (steps for a surface that has since changed or gone), revalidate-by dates that have passed. Catches STALE docs—was true once, is not now. Triggers on: "/doc-rot", "doc-rot", "stale docs", "outdated docs", "is this doc still current". Mechanical layer = deterministic age-markers (versions, dates, TODO markers, badges—~free, report-only); semantic layer = judging whether a flagged marker is actually rotten and spotting undated superseded content (paid, consent-gated). Severity judged by context, never mechanical; CONFIRMED and SUSPECTED reported separately.

1 other project uses a version of this.

Adopted by

Most recently taken up by

  • Other versions1 project uses a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 1

    1. jerseycheese/agent-skills★ 4same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • In this repository6 other files it gives its agents.

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    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
  1. Distinctive:

    After any report in an interactive session you MUST present this menu via your question tool (skip only when findings are zero or no user …

    line 52
  2. Distinctive:

    NEVER auto-fix: rewriting superseded instructions (a content decision), deleting sections, anything whose current truth you did not verify.

    line 58
  3. Very specific:

    If this canary misbehaves, OFFER to file it at <https://github.com/TheColliery/CoalLedger/issues> with a user-reviewed summary—never …

    line 64

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Doc-Rot

Answer in the USER'S language; keep technical terms, commands, paths, and check ids verbatim.

Find doc content that time has invalidated. Report CONFIRMED rot; park the merely-old in SUSPECTED.

Parameters

  • SCOPE: named files (default when given) | touched doc files this session | whole repo docs—.md/.mdx/.markdown/.rst/.txt/.adoc/.asciidoc/.org (confirm first if > 20 files).
  • TIER: Quick = mechanical age-markers only (~free) · Full = semantic staleness judgment (paid). Default from quickVsFull (.coalledger.json, global + project merge); Full is always a separate consent.

Age-markers (mechanical layer—deterministic detection)

markersignal
version stringdoc names a version older than the project's current one (compare against the version's source of truth, e.g. the manifest)
date stampa "last updated" / revalidate-by / verified-on date far in the past or already passed
dead task markerTODO / FIXME / "coming soon" / "not yet" with no sign of life
stale badgea hardcoded status/version badge the repo state contradicts

Detection is deterministic; whether a marker means ROT is not—an old date on an archive is fine, on an install guide it is not.

Method

  1. Quick: collect age-markers per the table. Old ≠ rotten: a marker alone lands in SUSPECTED.
  2. Full: judge each marker in context, and hunt UNDATED rot—instructions for a surface that has changed, claims a later doc superseded (pure contradiction between live docs belongs to doc-consistency; rot is the time axis).
  3. Confirm before CONFIRMED: a finding is CONFIRMED only when the current state contradicts the doc (the version source names a newer version; the referenced surface is gone). Anything inferred stays SUSPECTED.
  4. Severity by CONTEXT (never a fixed map), then honor severityFloor: rotten install/security steps readers follow = HIGH-CRITICAL; a stale badge or version mention = MEDIUM; an old date in an archived doc = LOW. scanEverything: true bypasses the floor this run—report everything down to low—and say so: state that severityFloor was bypassed, never that every scope cut was bypassed (this canary has none to bypass).

Escalation boundary

Whether a claim was EVER true is doc-grounding's job; formal verification of a high-stakes claim escalates to CoalBoard (/coalboard) if that skill is installed. This canary only answers "did time break it".

Grants & denials (CLASSIFY-BLOCK)

classstep it powersgranton denial
readcollect age-markers + check the version source of truthRead·Grep·Globrefuse that file, report it unscanned—never a false clean bill
writeApply safe fixes (unambiguous current-value updates)Write·Edit (·Bash—checkpoint via git stash/commit)report + courier the intended change to the dispatcher; never claim applied

A denial reaches the WORKER as a visible message and propagates NO further—not to the dispatcher, not as a catchable condition. Every row above states a branch or an explicit death; a step that dies says so in the output. Never report a denied step as done, skipped, or clean.

Output

| # | path:line | marker | evidence (current state) | severity | fix |

CONFIRMED table only; SUSPECTED (old-but-unproven) as a separate list, never the main table.

Reporting: call ReportFindings when callable—file/line MUST be the marker's own line, never a paraphrase; an unresolvable line reports your best guess, named imprecise in the wrap-up, never dropped. Severity prefixed in summary (e.g. [HIGH] …) per the severity-by-context rule above, ranked most-severe first, SUSPECTED (old-but-unproven) as verdict: PLAUSIBLE; chat then carries only the wrap-up line (counts · SUSPECTED list · overflow past 32) + the fix menu, never a restatement. Not callable → the table above, unchanged. An Apply-fixes click = consent to the Apply-safe-fixes class below (unambiguous current-value updates only), composing with—never bypassing—Fix mode. After any fix round, re-report the same findings with outcome: fixed/skipped/no_change_needed.

Fix mode (choice-gated)

After any report in an interactive session you MUST present this menu via your question tool (skip only when findings are zero or no user is present). NEVER auto-fix a live doc.

  • Apply safe fixes: only updates whose current value is unambiguous (bump a version string to the manifest's, refresh a date the user confirms, delete a TODO the user confirms dead). Each fix: checkpoint (git stash/commit in a git repo; else copy the file aside—never assume git exists) -> apply -> re-read the changed lines.
  • Let me pick: list findings; the user selects.
  • Report only: exit unchanged.

NEVER auto-fix: rewriting superseded instructions (a content decision), deleting sections, anything whose current truth you did not verify.

Multilingual

Age-markers are language-agnostic (versions, dates, and badges look the same in any prose language; date FORMATS vary—parse by structure, not an English month name). Semantic judgment degrades to low-confidence flags on a poorly-handled language, never false alarms.

Problem report

If this canary misbehaves, OFFER to file it at https://github.com/TheColliery/CoalLedger/issues with a user-reviewed summary—never auto-submit.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.

Check your setup, free