Doc quality
Docs-health canary suite for AI coding agents - CoalMine for documentation. 6+1 canaries, with doc-structure detected by a zero-dep CommonMark+GFM AST engine; severity by context, fixes choice-gated, never auto-applied. Also nudges quietly when docs change but MEMORY.md does not. Part of TheColliery.
npx -y skills add TheColliery/CoalLedger --skill doc-qualityAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
2 things to look at
- 28 days oldThe repository was created 28 days ago. New is not bad, but a brand new repository carrying a familiar-sounding name is the shape a typosquat arrives in, and there has been no time for anyone else to find a problem with it.
- 2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
What its author says it does
Copied from the file, not written here
Docs-health readability scan — two axes: QUALITY (bloat: filler, repetition, walls of text, buried leads; clarity: unexplained jargon, ambiguity, sentences that fight the reader) and language MECHANICS (typo, grammar, spelling, orthography — including script-level defects like decomposed characters that render right but break search, doubled spaces, wrong ellipsis/quote characters, spacing rules of the doc's language). Catches UNREADABLE or MALFORMED-LANGUAGE docs. Triggers on: "/doc-quality", "doc-quality", "tighten this doc", "proofread", "typos and grammar", "is this readable". Mechanical layer = deterministic mechanics (Unicode normalization, spacing, punctuation shape — ~free, report-only); semantic layer = bloat/clarity judgment + grammar in context (paid, consent-gated). Honors the project's own style/language rules where defined. Severity judged by context, never mechanical.
SKILL.md
4.6 KB, as published. Nobody here has run it
Doc-Quality
Answer in the USER'S language; keep technical terms, commands, paths, and check ids verbatim.
Find what makes a doc hard to read or mechanically malformed. Report CONFIRMED findings; style opinions stay SUSPECTED.
Parameters
- SCOPE: named files (default when given) | touched doc files this session | whole repo docs (confirm first if > 20 files).
- TIER: Quick = mechanical mechanics only (~free) · Full = adds bloat/clarity + grammar-in-context (paid). Default from
.coalledger.jsonquickVsFull; Full is always a separate consent.
The two axes
| axis | layer | catches |
|---|---|---|
| language mechanics | mechanical | decomposed characters that render identically but break search/sort (normalize-and-compare), doubled spaces, mixed or wrong quote/ellipsis/dash characters, the doc language's own spacing/orthography rules, obvious misspellings |
| quality | semantic | filler and repetition (the same point twice), walls of text, buried leads, unexplained jargon for the doc's audience, ambiguous instructions |
Method
- House rules first: if the project defines its own style or language rules (a style guide, formatting conventions, per-language orthography rules), those BIND — enforce them over any general rule, and never fight a documented deliberate choice.
- Quick (mechanics): deterministic checks per the table — a mechanics finding is CONFIRMED only when it is objectively wrong in the doc's language (a decomposed character, a doubled space), not a stylistic preference.
- Full (quality): judge bloat/clarity for the doc's audience and purpose. A cut proposal must not change meaning — quality fixes trim fat, never meat. Grammar/typo judgment runs in the doc's own language.
- Word-choice is a MEANING decision, not a typo: an unusual-but-intentional word, register, or voice gets flagged as SUSPECTED with a question, never "corrected".
- Severity by CONTEXT (never a fixed map), then honor
severityFloor: an ambiguous instruction readers must execute = HIGH; heavy bloat on a front-door doc = MEDIUM; a typo in prose = LOW (a typo inside a command or identifier is doc-grounding territory — it breaks, it does not just read badly).
Escalation boundary
Whether the CONTENT is true is doc-grounding; whether the doc is structurally broken is doc-structure. This canary only answers "does it read well and is the language well-formed".
Output
| # | path:line | axis | finding | severity | fix |
CONFIRMED table only; SUSPECTED (style/word-choice questions) as a separate list, never the main table.
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: mechanics only (recompose characters, collapse doubled spaces, unify punctuation per the house rule). 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 (including proposed prose trims, shown as before/after); the user selects.
- Report only: exit unchanged.
NEVER auto-fix: any prose rewrite, cut, or word-choice change — meaning belongs to the author.
Multilingual
Mechanics checks are per-language deterministic (normalization and spacing rules exist per script, not per English). Semantic quality judgment works in the doc's language and degrades to low-confidence SUSPECTED 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.