existential-birds/beagle/ensure-docs

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:

1. Symbol coverage — are the functions, classes, and modules documented to the language's standard (docstrings, JSDoc, GoDoc)? This is the per-language verification below.
2. 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.

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

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

1. 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, and findings (array, possibly empty).

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

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

1. Generation — Only if --report-only is 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.

1. 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/A with a one-line reason (e.g. tool not configured); remaining issues are listed or cleared.

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:

Flag, in priority order:

1. 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.
2. A thin type — present but doesn't cover the project's major features or surfaces.
3. 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-only to 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.