doc-gap-check
Skill0 starsChanged 2 months agoApache-2.0View on GitHub
Run the doc-gap-finder reducer subagent over the per-node enrichment sidecars + the concept catalog + the live documentation site. Produces or refreshes `lineage/{repo}/doc-gaps.md` — a ranked list of DOC-NNN candidates (broken URLs, missing anchors, code-doc drift, missing pages, coverage gaps, stale pages) with full citations the maintainer triages into the backlog.
In this repository27 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- alignSkill
- code-walkSkill
- conceptsSkill
- contributeSkill
- coverageSkill
- enrichSkill
- enumerateSkill
- find-implicit-adrsSkill
- implementSkill
- ingest-docsSkill
- log-issueSkill
- navigateSkill
- next-batchSkill
- orientSkill
- panelSkill
- probe-defineSkill
- probe-runSkill
- probeSkill
- reflect-featureSkill
- retrieveSkill
- reviewSkill
- scanSkill
- statusSkill
- streamsSkill
- test-coverageSkill
- triageSkill
The file
We split this skill into the rules it gives an agent
7 rules. About 0 are common, 1 is distinctive, and 6 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 25
Before spawning the subagent in default (incremental) mode, the skill computes:
- Distinctive: line 47
Read these (skip if loaded this session):
- Very specific: line 59
SUMMARY.md: prefer ../documentation/docs/SUMMARY.md (local sibling).
- Very specific: line 60
Substrate state: read lineage/{repo}/manifest.yaml's last_scan_commit so the produced report can record generated_at_commit.
- Very specific: line 61
Existing F-NNN findings: read findings/docs-coverage-undocumented-features/*.md paths so the subagent can cross-reference (not duplicate).
- Very specific: line 88
Verify each finding entry has category, surfaced_by, evidence, proposed_doc_action, severity.
- Very specific: line 106
Cross-reference, don't duplicate: If a finding matches DOC-163's F-NNN catalog, the entry's cross_references field cites the F-NNN.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Doc-gap check (DOC-164 slice 7+)
Build or refresh the cross-sidecar doc-gap report at lineage/{repo}/doc-gaps.md. The doc-gap-finder reducer walks every per-node sidecar's docs_link_semantic block, re-WebFetches each claimed URL to verify status + anchor + content alignment, joins the concept catalog (concepts.yaml) against the live documentation/docs/SUMMARY.md to surface concept-without-page gaps, runs the Type-5 bidirectional drift probe per adrs/drafts/research/agentic-code-ontology/PROBES.md, and writes a ranked candidate list the maintainer triages.
This skill is the third reducer in the agentic-code-ontology layer (per adrs/drafts/agentic-code-ontology.md rev 2). The first per-node enrichment slice was /enrich (slice 5). The first reducer was /concepts (slice 6 — concept catalog). /doc-gap-check (slice 7) consumes both.
Argument forms
| Form | Behaviour |
/doc-gap-check [<repo>] | Default. Run doc-gap-finder in incremental mode (per playbooks/reducer-incremental-mode.md) against the sidecar set + concepts.yaml + live docs (default repo: odd-platform). Refreshes lineage/{repo}/doc-gaps.md by appending+annotating only the sidecars whose node_id is not yet in the prior artefact's processed_node_ids. Preserves any maintainer-curated entries from a prior version. |
/doc-gap-check --full [<repo>] | Forces FULL mode — re-reads every sidecar and re-WebFetches every URL from scratch. Use when prior artefact is corrupt or after a sweep recalibration. |
/doc-gap-check --show [<repo>] | Read-only. Print the existing report's summary (counts per category + severity, top-5 highest-severity findings, cross-references). No subagent invocation. |
/doc-gap-check --diff [<repo>] | Read-only. Compare the existing doc-gaps.md to a freshly-generated one (in a temp file) and surface the diff. Useful for previewing what a refresh would change. |
Incremental input resolution
Before spawning the subagent in default (incremental) mode, the skill computes:
PROCESSED_NODE_IDS— read from priordoc-gaps.md's frontmatterprocessed_node_ids:. Missing →--fullfallback.NEW_SIDECAR_FILES— sidecars whosenode_idis not inPROCESSED_NODE_IDS. Empty set → exit.PRIOR_HEAD— one line per existingDOC-GAP-NNNfrom priordoc-gaps.md, derived viagrep -E '^## DOC-GAP-'+ severity + category. Compact-head shape per the playbook.CURATED_ENTRIES— verbatim Markdown of every entry flaggedmaintainer_curated: true.NEXT_AVAILABLE_ID— max existingDOC-GAP-NNN+ 1.
These get passed to the subagent in place of the legacy "full prior artefact" block. Live URLs are still re-verified per Rule 1 (the playbook does NOT relax the live-URL requirement — only the prior-artefact-reading cost).
Prerequisites
lineage/{repo}/understanding/{slug}.mdsidecars exist (i.e./enrichhas been run at least once).lineage/{repo}/concepts.yamlexists (i.e./conceptshas been run after the most recent enrichment).documentation/docs/SUMMARY.mdis reachable (local at../documentation/docs/SUMMARY.mdpreferred; livehttps://docs.opendatadiscovery.org/fallback).WebFetchtool is available — every URL gets verified live; stale verification copied from sidecars is forbidden by the subagent's Rule 1.findings/docs-coverage-undocumented-features/2026-05-08.mdis read for cross-reference (existing F-047..F-060 candidates) so the reducer doesn't duplicate.
Protocol
1. Orient
Read these (skip if loaded this session):
CLAUDE.md— quality baradrs/drafts/agentic-code-ontology.md— the layered ADR + reducer pattern.claude/agents/doc-gap-finder.md— the subagent's system promptfindings/docs-coverage-undocumented-features/2026-05-08.md— DOC-163 prior findings (cross-reference target so the reducer doesn't double-file)
2. Resolve inputs
- Sidecar set:
Globlineage/{repo}/understanding/*.md. Confirm at least one sidecar exists; otherwise report "no sidecars to walk — run/enrichfirst" and exit. - Concepts catalog:
lineage/{repo}/concepts.yaml. Confirm exists; if not, report "concepts.yaml missing — run/conceptsfirst" and exit (the reducer joins concepts × SUMMARY.md). - Existing doc-gaps:
lineage/{repo}/doc-gaps.md. Capture maintainer-curated entries (maintainer_curated: true) for preservation. - SUMMARY.md: prefer
../documentation/docs/SUMMARY.md(local sibling). Fallback: WebFetchhttps://docs.opendatadiscovery.org/. - Substrate state: read
lineage/{repo}/manifest.yaml'slast_scan_commitso the produced report can recordgenerated_at_commit. - Existing F-NNN findings: read
findings/docs-coverage-undocumented-features/*.mdpaths so the subagent can cross-reference (not duplicate).
3. Spawn the doc-gap-finder subagent
Invoke via Agent tool with subagent_type: doc-gap-finder (after .claude/agents/doc-gap-finder.md is loaded; in transient sessions general-purpose is the fallback). Construct the prompt as:
REPO: <repo>
WORKSPACE_ROOT_ABS: <absolute>
SIDECAR_DIR_ABS: /home/.../lineage/{repo}/understanding/
CONCEPTS_YAML_PATH: /home/.../lineage/{repo}/concepts.yaml
DOC_SUMMARY_PATH: <absolute path to ../documentation/docs/SUMMARY.md or live URL>
SUBSTRATE_LAST_SCAN_COMMIT: <from manifest.yaml>
EXISTING_DOC_GAPS: <verbatim content of lineage/{repo}/doc-gaps.md if present, else "(none)">
EXISTING_DOC_NNN_FINDINGS: <list of paths to findings/docs-coverage-undocumented-features/*.md for cross-reference>
TARGET_PATH: lineage/{repo}/doc-gaps.md
SIDECAR_COUNT: <N>The subagent's tool surface per its frontmatter is Read, Glob, Grep, WebFetch, Write. It writes the report and replies with Wrote: ... + Findings: ....
4. Validate the resulting report
After completion:
- Confirm
lineage/{repo}/doc-gaps.mdexists. - Parse YAML frontmatter (
generated_at,total_findings,findings_by_severity, etc.). Missing keys are an error. - Verify each finding entry has
category,surfaced_by,evidence,proposed_doc_action,severity. Missing field = log warning + report. - Spot-check 3-5 random findings: do their
surfaced_bysidecar references resolve to real files? Do theirevidenceURLs resolve when re-fetched? - HIGH-severity findings get an extra check: the maintainer triages these first; if the evidence is thin (single sidecar, no live-fetch confirmation), demote to MEDIUM and warn.
5. Report
Concise output:
- Report path
- Counts:
<H> HIGH / <M> MEDIUM / <L> LOW = <N> total findings - Categories:
broken-url: n, missing-anchor: n, drift: n, missing-page: n, stale-page: n, coverage-gap: n - Top-5 HIGH findings (one-liners with finding IDs)
- Cross-references to DOC-163's F-NNN:
<count>findings overlap with prior cataloged gaps - Suggested next:
/triage findings/docs-coverage-undocumented-features/2026-05-08.mdto catalog these as DOC-NNN backlog items, then/conceptsto refresh the catalog if doc additions changed canonical-vocab.
Rules
- Live-URL-only re-verification. The doc-gap-finder MUST WebFetch every URL fresh in the session. Stale verifications copied from sidecars are forbidden — the subagent's prompt enforces this; the skill double-checks via spot-fetch on 3-5 sampled URLs.
- Cross-reference, don't duplicate. If a finding matches DOC-163's F-NNN catalog, the entry's
cross_referencesfield cites the F-NNN; the finding does NOT re-file the same gap as a new entry. - Severity is anchored to operator impact. HIGH = operator follows the doc → broken/insecure deployment. MEDIUM = partial coverage / wrong-slug-but-resolvable. LOW = cosmetic. The skill rejects HIGH findings with thin evidence and warns to demote.
- Maintainer-curated entries preserved. Existing
maintainer_curated: trueentries in priordoc-gaps.mdsurvive verbatim through refreshes (the subagent readsEXISTING_DOC_GAPSand preserves; the skill verifies preservation in step 4). - Reducer doesn't fix. The subagent surfaces gaps; it doesn't author doc pages. Maintainer triages into DOC-NNN, then
/implementslices ship the doc updates.
Failure modes to surface
- WebFetch fails repeatedly (network outage, rate-limit on docs.opendatadiscovery.org) → surface as a partial run; the existing
doc-gaps.mdis preserved; no auto-write. - Subagent reports HIGH findings whose
surfaced_bydoesn't cite a sidecar → CRITICAL; reject the report; ask for prompt revision. - More than 50% of findings cite the same single sidecar → likely sidecar-quality issue, not doc gap; surface to maintainer for sidecar refresh via
/enrich --node <id>. - Severity distribution skewed (e.g. >70% HIGH) → likely severity-inflation; surface for maintainer recalibration.
Cross-references
- Subagent:
.claude/agents/doc-gap-finder.md - Inputs:
lineage/{repo}/understanding/*.md+lineage/{repo}/concepts.yaml - Output:
lineage/{repo}/doc-gaps.md - Live source-of-truth:
https://docs.opendatadiscovery.org/+../documentation/docs/SUMMARY.md - Cross-reference target:
findings/docs-coverage-undocumented-features/*.md(DOC-163 F-NNN catalog) - ADR:
adrs/drafts/agentic-code-ontology.mdrev 2 (slice 7) - Probe spec:
adrs/drafts/research/agentic-code-ontology/PROBES.md(Type-5 bidirectional drift probe) - Cornerstone enforced: documentation pillar Cornerstone 1 (discoverability without context)
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

