Ensure Documentation Coverage
Verify documentation coverage across a codebase, report gaps, and generate missing docs. If the agent supports subagents, dispatch one verifier per detected language in parallel; otherwise run the same per-language verification sequentially — the output is identical either way.
Coverage has two complementary lenses, and a healthy project needs both:
- Symbol coverage — are the functions, classes, and modules documented to the language's standard (docstrings, JSDoc, GoDoc)? This is the per-language verification below.
- Diataxis type balance — does the doc set as a whole serve all four user needs: a Tutorial to learn, How-To guides for tasks, Reference for lookups, and Explanation for understanding? A codebase can have 100% docstring coverage and still have no way for a newcomer to get started. See the Diataxis balance check below.
Workflow
Complete steps in order. Do not advance until each step’s Pass is satisfied.
-
Language detection — Follow Phase 1 (language detection) in
references/workflow.md.- Pass: For each language you will verify, you have evidence of at least one matching source file (counts or command output); if none qualify, stop with a short “no applicable languages” message and do not run verifiers.
-
Load standards — Read the sections for your detected languages (language standards, verifier prompts, consolidation format) in the same reference file.
- Pass: You can state which standard applies per language (e.g. Google docstrings, JSDoc, GoDoc) before verification begins.
-
Verification — Verify each qualifying language using the verifier prompts and JSON output shape in the reference (Phase 2). If the agent supports subagents, run one verifier per language in parallel; otherwise run them sequentially.
- Pass: Each completed verification returns parseable JSON including
language,files_scanned, andfindings(array, possibly empty).
- Pass: Each completed verification returns parseable JSON including
-
Diataxis balance check — Run the Diataxis type balance check against the project's existing docs (e.g. a
docs/tree, README, or wiki).- Pass: You can state, for each of the four types (Tutorial, How-To, Reference, Explanation), whether the project has at least one document serving that need, and you have noted any missing or thin type.
-
Consolidated report — Merge results per Phase 3 (summary table, severity grouping, detailed findings if requested). Include the Diataxis balance alongside symbol coverage.
- Pass: The user sees the merged report (inline or written to an agreed path) — covering both symbol coverage and Diataxis type balance — before you claim the audit is done or propose fixes.
-
Generation — Only if
--report-onlyis not set: offer choices per Phase 4; apply doc edits only after an explicit user choice to generate. For a missing Diataxis type, route generation through draft-docs for the relevant type rather than generating inline.- Pass: No documentation edits for gaps until the user selects an option that includes generation; if they decline or choose report-only behavior, end after the report.
-
Post-edit verification — After any generation, run or offer the linter commands in Phase 5 of the reference for languages you changed, when those tools exist in the repo.
- Pass: Linter run completed with output captured, or
N/Awith a one-line reason (e.g. tool not configured); remaining issues are listed or cleared.
- Pass: Linter run completed with output captured, or
Diataxis Type Balance Check
Survey the project's prose documentation (a docs/ tree, README, wiki, or doc site) and classify what exists into the four Diataxis types. Use the compass to classify — action or cognition? acquisition or application? — per docs-style/references/diataxis-compass.md.
Report the balance as a table:
| Type | Present? | Notes |
|---|---|---|
| Tutorial (learning) | yes / no / thin | e.g. "No getting-started / first-project guide" |
| How-To (tasks) | yes / no / thin | e.g. "Several task guides under docs/how-to/" |
| Reference (lookup) | yes / no / thin | e.g. "API reference generated, but no CLI reference" |
| Explanation (understanding) | yes / no / thin | e.g. "No architecture / design-rationale docs" |
Flag, in priority order:
- A missing type — the doc set serves none of that user need. The most common and most damaging gap is a missing Tutorial: a project can have exhaustive reference and still leave a newcomer with no way in.
- A thin type — present but doesn't cover the project's major features or surfaces.
- Mixed documents — a single page trying to be two types at once (e.g. reference tables embedded in a how-to). Recommend splitting via improve-doc.
Do not propose generating empty skeletons for missing types. Following the Diataxis "work by improvement" principle, recommend the single highest-value document to add or fix next, and offer to draft it via draft-docs.
Notes
- Use
--report-onlyto skip generation. - Avoid test files unless they are test helpers.
- Keep report output aligned with the language-specific standards in the reference file.
- The Diataxis balance check is about the doc set as a whole; per-language symbol coverage and type balance are independent — report both.
