> For the complete documentation index, see [llms.txt](https://docs.thecolliery.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thecolliery.org/tools/coalledger/canaries/skill-4.md).

# doc-rot

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

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)

| marker           | signal                                                                                                                      |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------- |
| version string   | doc names a version older than the project's current one (compare against the version's source of truth, e.g. the manifest) |
| date stamp       | a "last updated" / revalidate-by / verified-on date far in the past or already passed                                       |
| dead task marker | TODO / FIXME / "coming soon" / "not yet" with no sign of life                                                               |
| stale badge      | a 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)

| class | step it powers                                          | grant                                                    | on denial                                                                   |
| ----- | ------------------------------------------------------- | -------------------------------------------------------- | --------------------------------------------------------------------------- |
| read  | collect age-markers + check the version source of truth | `Read`·`Grep`·`Glob`                                     | refuse that file, report it unscanned—never a false clean bill              |
| write | Apply 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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.thecolliery.org/tools/coalledger/canaries/skill-4.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.