mgiovani/ai-arsenal / skills/docs-check
docs-check
VerifiedRead-only audit of documentation against the current codebase, flags stale docs, missing sections, broken links, and hallucinated claims (wrong file references, wrong counts, diagram entities that don't exist in code). Use for "check the docs", "audit documentation", "are the docs stale", "find hallucinations in docs", "docs health check", "does this doc still match the code", or before onboarding/release. Reports only, never edits files, for actually fixing or regenerating docs use docs-update instead.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.0 KB |
| evals/evals.json | config | 3.6 KB |
| evals/trigger-eval.json | config | 1.9 KB |
| references/scoring-criteria.md | markdown | 2.0 KB |
| references/verification-patterns.md | markdown | 4.8 KB |
evals/evals.json
View on GitHub{
"skill": "docs-check",
"evals": [
{
"id": "pre-release-full-doc-health-check",
"prompt": "We're cutting a release next week, run a full docs health check across the docs/ tree including ADRs and flag anything broken",
"assertions": [
"Scans the full docs/ tree including the ADR directory and identifies the documentation types present",
"For the multi-doc audit, either spawns parallel Explore subagents per document/section or, if no Task tool is available, explicitly states it is falling back to a sequential inline pass over each document",
"Validates Mermaid diagram syntax and checks for broken internal links using an actual command (grep/glob), not assumption",
"Outputs documents grouped into Good/Stale/Broken/Missing categories rather than 0-100 numeric scores or a weighted average",
"Recommends docs-update or docs-diagram (not itself) as the follow-up action for any Stale/Broken/Missing doc",
"Does not edit, write, or modify any documentation file during the run"
]
},
{
"id": "hallucinated-service-count-in-readme",
"prompt": "Our README says 'the platform has 5 microservices' — can you verify that's still accurate and find any other made-up claims in the docs?",
"assertions": [
"Counts actual services/components in the codebase (via find/glob/grep) and compares the number to the claim instead of assuming it's correct",
"Checks file/path references mentioned in the docs to confirm they actually exist",
"Reports a Hallucination Report section citing the verification command used as evidence for each false claim",
"Rates the README (or the section containing the false claim) as Broken rather than assigning it a numeric score",
"Does not modify or rewrite the README or any other doc file",
"Gives a specific, actionable recommendation naming a concrete follow-up command (e.g. docs-update) for the hallucination found"
]
},
{
"id": "focus-category-not-present-in-repo",
"prompt": "docs-check infrastructure — focus on our infrastructure docs",
"assertions": [
"Scans docs/ to see what categories of documentation actually exist before matching the requested focus, rather than assuming a fixed core/data/infrastructure/all taxonomy",
"If the repo has no infrastructure-related docs or infra signal (no Dockerfile/compose/k8s config) to check against, states this explicitly and lists the categories that were actually found instead of silently returning an empty or fabricated report",
"If infrastructure-related docs or config do exist, checks them against real deployment/Docker/config files rather than only checking for a file literally named 'deployment.md'",
"Does not invent scores or ratings for a category that doesn't exist in the repo"
]
},
{
"id": "user-asks-to-also-fix-what-it-finds",
"prompt": "Check the docs and fix whatever's broken while you're at it",
"assertions": [
"Performs the read-only audit (scans docs/, verifies claims, checks freshness/completeness/quality) and produces a report",
"States explicitly that it only reports and does not edit documentation, pointing to docs-update as the skill that performs fixes",
"Does not call Write or Edit (or any mutating command) on any documentation file at any point in the run, even for a fix it judges trivial or obvious",
"The final report still includes concrete, actionable recommendations (with a follow-up command) for each issue found, so declining to fix doesn't mean declining to report"
]
}
]
}
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |