Documentation Freshness
Detect documentation drift across any project. Reports findings without auto-fixing.
Context Discovery
Priority 1: Configuration
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).
Priority 2: Project Identity
Read CLAUDE.md and README.md to understand project structure, tech stack, and conventions.
Priority 3: Documentation Inventory
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).
Arguments
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) |
Scanning Tiers
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.
Mode Execution
scan (default)
- Run
scan_freshness.py for mechanical checks (links, versions, git staleness)
- Present script findings (broken links table, version mismatches, staleness scores)
- For stale/very_stale docs: use Grep/Read to check code-doc alignment on key references
- For docs covering the same topic: cross-check for consistency
- Produce the freshness report
links
- Run
scan_freshness.py --links-only
- Present broken links table directly from JSON output
- Group findings by severity: broken links first, then file_ref warnings
check <path>
- If path is a file, run link checker and version checker on that file only
- If path is a directory, scan all
.md files within it
- Use Grep to check file path references and function names against the codebase
- Report findings for the targeted scope
drift <path>
- Read the specified doc
- Extract: function/method names, API endpoints, file paths, config keys, class names
- Grep/Read the corresponding code to verify each reference still exists and is accurate
- Report mismatches with evidence (doc line vs code location)
cross-doc
- Run
scan_freshness.py to get doc inventory with headings
- Identify docs with overlapping topics (shared heading keywords)
- Read overlapping docs and compare factual claims
- Flag contradictions (e.g., different version requirements, conflicting setup steps)
report
Same as scan but write output to {output_dir}/{YYYY-MM-DD}-freshness.md.
claude-md
- Run
claude_md_checker.py to compare CLAUDE.md claims against filesystem
- Present findings by category: plugin counts, component inventories, versions, file paths
- Highlight undocumented components (CRITICAL) and version mismatches (WARNING)
onboard
- Run
frontmatter_onboard.py to find docs without tracking frontmatter
- Uses whitelist of known-maintained docs (READMEs, custom docs)
- Generates minimal
title + last_updated frontmatter from git history
- On user approval, apply with
--apply flag
setup
Scaffold a GitHub Actions workflow that runs joaquimscosta/docs-health-action@v1 on every PR.
- Check if
.github/workflows/ exists — create if needed
- Check if a docs-health workflow already exists — warn and offer to overwrite/skip
- Ask user which checks to enable (use
AskUserQuestion 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)
- Ask user for failure policy:
errors (default), warnings, or none (advisory)
- Generate
.github/workflows/docs-health.yml from template
- Show the generated file and confirm before writing
See WORKFLOW.md § setup for the full template.
Automation Integration
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 Levels
| 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 |
Output Rules
- Evidence-based: every finding backed by file path and line number
- Tabular: summary table first, detailed findings below
- Actionable: each finding includes what needs updating
- Detection only: NEVER auto-fix documentation
Lane Discipline
- Do NOT update or rewrite documentation — detection only
- Do NOT produce roadmap status, architecture analysis, or user stories
- Do NOT write source code
References
- WORKFLOW.md — Detection algorithms and convention tables
- EXAMPLES.md — Usage examples for each mode
- TROUBLESHOOTING.md — Common issues and fixes
1---2name: doc-freshness3description: Detect documentation drift, stale references, and cross-document inconsistencies in any project. Scans for code-doc drift (API/function changes not reflected in docs), cross-doc drift (conflicting information across documents), and stale references (broken links, deleted files, outdated versions). Use when checking "doc freshness", "stale docs", "documentation drift", "broken links", "outdated documentation", "doc accuracy", "docs out of date", "doc audit", "doc health", or "verify documentation".4---5
6# Documentation Freshness
7
8Detect documentation drift across any project. Reports findings without auto-fixing.
9
10## Context Discovery
11
12### Priority 1: Configuration
13
14Read `.arkhe.yaml` from project root. Extract `doc-freshness:` section for custom patterns, exclusions, and doc-code mappings.
15Extract `doc-health:` section for `output_dir` (used by `report` mode, default: `docs/health`).
16
17### Priority 2: Project Identity
18
19Read `CLAUDE.md` and `README.md` to understand project structure, tech stack, and conventions.
20
21### Priority 3: Documentation Inventory
22
23Run the scanner to discover all documentation files and perform mechanical checks:
24
25```bash
26python3 ${CLAUDE_SKILL_DIR}/scripts/scan_freshness.py <project-root>
27```
28
29Use `--links-only` for fast mode (links and file refs only, no git staleness).
30
31## Arguments
32
33Parse from `$ARGUMENTS`:
34
35| Mode | Description |
36|------|-------------|
37| `scan` | Full freshness analysis (all three drift types) |
38| `check <path>` | Focused analysis on one file or directory |
39| `links` | Broken links and stale references only (script-driven, fast) |
40| `drift <path>` | Code-doc drift for a specific doc or doc-code pair |
41| `cross-doc` | Cross-document consistency check |
42| `report` | Persist structured freshness report to `{output_dir}/` |
43| `claude-md` | CLAUDE.md structural drift (plugin counts, components, versions) |
44| `onboard` | Suggest/apply tracking frontmatter to docs that need it |
45| `setup` | Scaffold GitHub Actions workflow for docs-health-action CI |
46| _(none)_ | Full scan (same as `scan`) |
47
48## Scanning Tiers
49
50Documents are automatically classified into scanning tiers:
51
52| Tier | Detection | Checks Performed |
53|------|-----------|-----------------|
54| **Basic** | All `.md` files | Broken links, git age classification, backtick-path verification |
55| **Deep** | YAML frontmatter with `last_updated` or `version` | Basic + version drift, `last_updated` accuracy, cross-doc consistency |
56
57Tier is auto-detected per file. No configuration needed. The scanner JSON output includes `"tier"` per doc and `"tier_counts"` in the summary.
58
59## Mode Execution
60
61### `scan` (default)
62
631. Run `scan_freshness.py` for mechanical checks (links, versions, git staleness)
642. Present script findings (broken links table, version mismatches, staleness scores)
653. For stale/very_stale docs: use Grep/Read to check code-doc alignment on key references
664. For docs covering the same topic: cross-check for consistency
675. Produce the freshness report
68
69### `links`
70
711. Run `scan_freshness.py --links-only`
722. Present broken links table directly from JSON output
733. Group findings by severity: broken links first, then file_ref warnings
74
75### `check <path>`
76
771. If path is a file, run link checker and version checker on that file only
782. If path is a directory, scan all `.md` files within it
793. Use Grep to check file path references and function names against the codebase
804. Report findings for the targeted scope
81
82### `drift <path>`
83
841. Read the specified doc
852. Extract: function/method names, API endpoints, file paths, config keys, class names
863. Grep/Read the corresponding code to verify each reference still exists and is accurate
874. Report mismatches with evidence (doc line vs code location)
88
89### `cross-doc`
90
911. Run `scan_freshness.py` to get doc inventory with headings
922. Identify docs with overlapping topics (shared heading keywords)
933. Read overlapping docs and compare factual claims
944. Flag contradictions (e.g., different version requirements, conflicting setup steps)
95
96### `report`
97
98Same as `scan` but write output to `{output_dir}/{YYYY-MM-DD}-freshness.md`.
99
100### `claude-md`
101
1021. Run `claude_md_checker.py` to compare CLAUDE.md claims against filesystem
1032. Present findings by category: plugin counts, component inventories, versions, file paths
1043. Highlight undocumented components (CRITICAL) and version mismatches (WARNING)
105
106### `onboard`
107
1081. Run `frontmatter_onboard.py` to find docs without tracking frontmatter
1092. Uses whitelist of known-maintained docs (READMEs, custom docs)
1103. Generates minimal `title` + `last_updated` frontmatter from git history
1114. On user approval, apply with `--apply` flag
112
113### `setup`
114
115Scaffold a GitHub Actions workflow that runs `joaquimscosta/docs-health-action@v1` on every PR.
116
1171. Check if `.github/workflows/` exists — create if needed
1182. Check if a docs-health workflow already exists — warn and offer to overwrite/skip
1193. Ask user which checks to enable (use `AskUserQuestion` with multiSelect):
120 - `links` (broken internal links and anchors)
121 - `versions` (version references vs ground truth files)
122 - `staleness` (git-based documentation age)
123 - `claude-md` (CLAUDE.md structural drift — Claude Code projects only)
124 - `cross-doc` (cross-document version conflicts)
125 - `frontmatter` (missing tracking frontmatter)
1264. Ask user for failure policy: `errors` (default), `warnings`, or `none` (advisory)
1275. Generate `.github/workflows/docs-health.yml` from template
1286. Show the generated file and confirm before writing
129
130See [WORKFLOW.md](WORKFLOW.md) § `setup` for the full template.
131
132## Automation Integration
133
134**SessionStart Hook**: Critical-doc fast scan on session start (5-second timeout)
135```bash
136/doc:health --critical-only
137# Scans: README.md, CLAUDE.md only (root-level critical docs)
138```
139
140**PostToolUse Hook** (after `/commit`): Post-commit doc-impact checks
141```bash
142/doc:health drift
143# Checks if modified code files have corresponding documentation
144```
145
146**User-Driven (`/loop`)**: Periodic freshness monitoring
147```bash
148/loop 1h /doc:health links # Hourly broken-link checks
149/loop 4h /doc:health scan # Full scans every 4 hours
150```
151
152## Severity Levels
153
154| Severity | Meaning |
155|----------|---------|
156| **CRITICAL** | Broken link to deleted file, doc references removed API/function |
157| **WARNING** | Version mismatch, function signature changed, doc stale >30 days |
158| **INFO** | Minor inconsistency, doc aging (7-30 days), cosmetic drift |
159
160## Output Rules
161
162- **Evidence-based**: every finding backed by file path and line number
163- **Tabular**: summary table first, detailed findings below
164- **Actionable**: each finding includes what needs updating
165- **Detection only**: NEVER auto-fix documentation
166
167## Lane Discipline
168
169- Do NOT update or rewrite documentation — detection only
170- Do NOT produce roadmap status, architecture analysis, or user stories
171- Do NOT write source code
172
173## References
174
175- [WORKFLOW.md](WORKFLOW.md) — Detection algorithms and convention tables
176- [EXAMPLES.md](EXAMPLES.md) — Usage examples for each mode
177- [TROUBLESHOOTING.md](TROUBLESHOOTING.md) — Common issues and fixes
majiayu000