From doc
Detects documentation drift, stale references, and cross-document inconsistencies in projects. Scans code-doc mismatches, broken links, outdated versions, and git staleness.
npx claudepluginhub joaquimscosta/arkhe-claude-plugins --plugin docThis skill is limited to using the following tools:
Detect documentation drift across any project. Reports findings without auto-fixing.
Audits repo documentation under doc/ and READMEs (README.md, README-EN.md, README-ZH.md, mcp/README.md) for drift, stale statements, broken references, and mismatches during maintenance or before PRs.
Audits documentation staleness via git history and maintains quality with auto-fixes. Maps code paths to docs in $JAAN_DOCS_DIR. Use for reviewing or updating docs.
Audits codebase documentation for accuracy, completeness, and freshness by comparing against code structure. Auto-fixes small discrepancies in fix mode, reports structural changes. Works with any language/framework.
Share bugs, ideas, or general feedback.
Detect documentation drift across any project. Reports findings without auto-fixing.
Read .arkhe.yaml from project root. Extract doc-freshness: section for custom patterns, exclusions, and doc-code mappings.
Extract doc-health: section for output_dir (used by report mode, default: docs/health).
Read CLAUDE.md and README.md to understand project structure, tech stack, and conventions.
Run the scanner to discover all documentation files and perform mechanical checks:
python3 ${CLAUDE_SKILL_DIR}/scripts/scan_freshness.py <project-root>
Use --links-only for fast mode (links and file refs only, no git staleness).
Parse from $ARGUMENTS:
| Mode | Description |
|---|---|
scan | Full freshness analysis (all three drift types) |
check <path> | Focused analysis on one file or directory |
links | Broken links and stale references only (script-driven, fast) |
drift <path> | Code-doc drift for a specific doc or doc-code pair |
cross-doc | Cross-document consistency check |
report | Persist structured freshness report to {output_dir}/ |
claude-md | CLAUDE.md structural drift (plugin counts, components, versions) |
onboard | Suggest/apply tracking frontmatter to docs that need it |
setup | Scaffold GitHub Actions workflow for docs-health-action CI |
| (none) | Full scan (same as scan) |
Documents are automatically classified into scanning tiers:
| Tier | Detection | Checks Performed |
|---|---|---|
| Basic | All .md files | Broken links, git age classification, backtick-path verification |
| Deep | YAML frontmatter with last_updated or version | Basic + version drift, last_updated accuracy, cross-doc consistency |
Tier is auto-detected per file. No configuration needed. The scanner JSON output includes "tier" per doc and "tier_counts" in the summary.
scan (default)scan_freshness.py for mechanical checks (links, versions, git staleness)linksscan_freshness.py --links-onlycheck <path>.md files within itdrift <path>cross-docscan_freshness.py to get doc inventory with headingsreportSame as scan but write output to {output_dir}/{YYYY-MM-DD}-freshness.md.
claude-mdclaude_md_checker.py to compare CLAUDE.md claims against filesystemonboardfrontmatter_onboard.py to find docs without tracking frontmattertitle + last_updated frontmatter from git history--apply flagsetupScaffold a GitHub Actions workflow that runs joaquimscosta/docs-health-action@v1 on every PR.
.github/workflows/ exists — create if neededAskUserQuestion with multiSelect):
links (broken internal links and anchors)versions (version references vs ground truth files)staleness (git-based documentation age)claude-md (CLAUDE.md structural drift — Claude Code projects only)cross-doc (cross-document version conflicts)frontmatter (missing tracking frontmatter)errors (default), warnings, or none (advisory).github/workflows/docs-health.yml from templateSee WORKFLOW.md § setup for the full template.
SessionStart Hook: Critical-doc fast scan on session start (5-second timeout)
/doc:health --critical-only
# Scans: README.md, CLAUDE.md only (root-level critical docs)
PostToolUse Hook (after /commit): Post-commit doc-impact checks
/doc:health drift
# Checks if modified code files have corresponding documentation
User-Driven (/loop): Periodic freshness monitoring
/loop 1h /doc:health links # Hourly broken-link checks
/loop 4h /doc:health scan # Full scans every 4 hours
| Severity | Meaning |
|---|---|
| CRITICAL | Broken link to deleted file, doc references removed API/function |
| WARNING | Version mismatch, function signature changed, doc stale >30 days |
| INFO | Minor inconsistency, doc aging (7-30 days), cosmetic drift |