Doc-Standard
Answer in the USER'S language; keep technical terms, commands, paths, and check ids verbatim.
Find what a doc is MISSING versus the standard for its kind. Report CONFIRMED gaps only.
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 presence checks (~free) · Full = semantic completeness judgment (paid). Default from
quickVsFull (.coalledger.json, global + project merge); Full is always a separate consent.
The standard (resolve in this order — never invent one)
- The project's own — a style guide, template, pattern doc, or stated convention in the repo binds first.
- The kind's accepted standard — verified REAL-TIME, MULTI-source (cross-check several authoritative sources, never one), language-aware. Offline →
⚠️ unverified: check [source], never asserted from memory.
- No resolvable standard → say so; report only self-evident gaps (an empty required field, a heading with no body).
Method
- Identify the doc's kind (README, policy, reference, report, letter, ...) and resolve its standard (above).
- Mechanical layer: required parts PRESENT — an agent read detects sections by structure, position, and meaning, NEVER by an English keyword (a section may carry its heading in any language). No parser: doc-standard ships no engine (doc-structure's AST is that skill's own, not shared).
- Semantic layer (Full): completeness of substance — is the public surface the source ships actually covered (commands, config keys, exported APIs, the steps a reader needs); are stated sections empty shells.
- Severity by CONTEXT (never a fixed map), then honor
severityFloor: a missing security-reporting channel or install step = HIGH-CRITICAL; an undocumented public key = MEDIUM-HIGH; a nice-to-have section = 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 content is CORRECT is doc-grounding's job; whether a judgment call needs formal verification is CoalBoard's (/coalboard, if that skill is installed). This canary only answers "is it all THERE".
Grants & denials (CLASSIFY-BLOCK)
| class |
step it powers |
grant |
on denial |
| read |
detect required parts by reading the doc |
Read·Grep·Glob |
refuse that file, report it unscanned — never a false clean bill |
| write |
Draft the missing parts (after approval) |
Write·Edit (·Bash — checkpoint via git stash/commit) |
report + courier the intended change to the dispatcher; never claim applied |
| network |
resolving the kind's accepted standard |
WebSearch·WebFetch |
already covered — resolving the standard already degrades to ⚠️ unverified: check [source] when offline (see "The standard" above) |
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 | gap | standard source | severity | fix |
CONFIRMED table only; ⚠️ unverified standards and SUSPECTED gaps in separate lists.
Reporting: call ReportFindings when callable — file/line MUST be the defect site, 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, ⚠️ unverified standards AND SUSPECTED gaps both report as verdict: PLAUSIBLE (Output's own two non-CONFIRMED lists, same non-CONFIRMED shape); chat then carries only the wrap-up line (counts · unverified + SUSPECTED lists · overflow past 32) + the fix menu, never a restatement. Not callable → the table above, unchanged. No mechanical safe-fix class exists here — every fix is a drafted section awaiting approval, so an Apply-fixes click degrades to the Draft/Let-me-pick path below, never an auto-apply. 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.
- Draft the missing parts: propose section drafts for the user to review — content is ALWAYS the user's call; drafts are applied only after approval, with a checkpoint first (git stash/commit in a git repo; else copy the file aside — never assume git exists).
- Let me pick: list gaps; the user selects which to draft.
- Report only: exit unchanged.
Multilingual
The mechanical layer is language-agnostic (structure/position/semantics, an agent read, no keyword matching). Semantic judgment works in the doc's language and 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.
1---2name: doc-standard3description: Docs-health completeness scan — a doc measured against its KIND's standard: required sections present, public surface documented (every command/config key/exported API the code ships appears in the doc), the shape the genre expects (a README's install path, a security policy's reporting channel, a formal letter's parts). Catches INCOMPLETE docs. The standard is the project's OWN declared one first (a style guide, template, or pattern doc in the repo), else the kind's widely-accepted standard verified REAL-TIME against MULTIPLE authoritative sources. Triggers on: "/doc-standard", "doc-standard", "is this doc complete", "missing sections", "audit doc completeness". Mechanical layer (sections/hierarchy present, detected by structure/position/meaning — an agent read, never an English keyword) + semantic layer (completeness judgment, consent-gated). Offline degrades safe to "⚠️ unverified". Severity judged by context, never mechanical.4---56# Doc-Standard78Answer in the USER'S language; keep technical terms, commands, paths, and check ids verbatim.910Find what a doc is MISSING versus the standard for its kind. Report CONFIRMED gaps only.1112## Parameters13- **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).14- **TIER:** Quick = mechanical presence checks (~free) · Full = semantic completeness judgment (paid). Default from `quickVsFull` (`.coalledger.json`, global + project merge); Full is always a separate consent.1516## The standard (resolve in this order — never invent one)171. **The project's own** — a style guide, template, pattern doc, or stated convention in the repo binds first.182. **The kind's accepted standard** — verified REAL-TIME, MULTI-source (cross-check several authoritative sources, never one), language-aware. Offline → `⚠️ unverified: check [source]`, never asserted from memory.193. **No resolvable standard** → say so; report only self-evident gaps (an empty required field, a heading with no body).2021## Method221. **Identify the doc's kind** (README, policy, reference, report, letter, ...) and resolve its standard (above).232. **Mechanical layer:** required parts PRESENT — an agent read detects sections by structure, position, and meaning, NEVER by an English keyword (a section may carry its heading in any language). No parser: doc-standard ships no engine (doc-structure's AST is that skill's own, not shared).243. **Semantic layer (Full):** completeness of substance — is the public surface the source ships actually covered (commands, config keys, exported APIs, the steps a reader needs); are stated sections empty shells.254. **Severity by CONTEXT** (never a fixed map), then honor `severityFloor`: a missing security-reporting channel or install step = HIGH-CRITICAL; an undocumented public key = MEDIUM-HIGH; a nice-to-have section = 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).2627## Escalation boundary28Whether content is CORRECT is doc-grounding's job; whether a judgment call needs formal verification is CoalBoard's (`/coalboard`, if that skill is installed). This canary only answers "is it all THERE".2930## Grants & denials (CLASSIFY-BLOCK)31| class | step it powers | grant | on denial |32|---|---|---|---|33| read | detect required parts by reading the doc | `Read`·`Grep`·`Glob` | refuse that file, report it unscanned — never a false clean bill |34| write | Draft the missing parts (after approval) | `Write`·`Edit` (·`Bash` — checkpoint via git stash/commit) | report + courier the intended change to the dispatcher; never claim applied |35| network | resolving the kind's accepted standard | `WebSearch`·`WebFetch` | already covered — resolving the standard already degrades to `⚠️ unverified: check [source]` when offline (see "The standard" above) |3637A 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.3839## Output40| # | path | gap | standard source | severity | fix |4142CONFIRMED table only; `⚠️ unverified` standards and SUSPECTED gaps in separate lists.4344**Reporting:** call `ReportFindings` when callable — `file`/`line` MUST be the defect site, 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, `⚠️ unverified` standards AND SUSPECTED gaps both report as `verdict: PLAUSIBLE` (Output's own two non-CONFIRMED lists, same non-CONFIRMED shape); chat then carries only the wrap-up line (counts · unverified + SUSPECTED lists · overflow past 32) + the fix menu, never a restatement. Not callable → the table above, unchanged. **No mechanical safe-fix class exists here** — every fix is a drafted section awaiting approval, so an Apply-fixes click degrades to the Draft/Let-me-pick path below, never an auto-apply. After any fix round, re-report the same findings with `outcome: fixed`/`skipped`/`no_change_needed`.4546## Fix mode (choice-gated)47After 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.4849- **Draft the missing parts:** propose section drafts for the user to review — content is ALWAYS the user's call; drafts are applied only after approval, with a checkpoint first (git stash/commit in a git repo; else copy the file aside — never assume git exists).50- **Let me pick:** list gaps; the user selects which to draft.51- **Report only:** exit unchanged.5253## Multilingual54The mechanical layer is language-agnostic (structure/position/semantics, an agent read, no keyword matching). Semantic judgment works in the doc's language and degrades to low-confidence flags on a poorly-handled language, never false alarms.5556## Problem report57If this canary misbehaves, OFFER to file it at <https://github.com/TheColliery/CoalLedger/issues> with a user-reviewed summary — never auto-submit.
TheColliery