Arkhe-claude-plugins doc-freshness

install

source · Clone the upstream repo

git clone https://github.com/joaquimscosta/arkhe-claude-plugins

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/joaquimscosta/arkhe-claude-plugins "$T" && mkdir -p ~/.claude/skills && cp -r "$T/plugins/doc/skills/doc-freshness" ~/.claude/skills/joaquimscosta-arkhe-claude-plugins-doc-freshness && rm -rf "$T"

manifest: plugins/doc/skills/doc-freshness/SKILL.md

source content

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

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

Arkhe-claude-plugins doc-freshness

Documentation Freshness

Context Discovery

Priority 1: Configuration

Priority 2: Project Identity

Priority 3: Documentation Inventory

Arguments

Scanning Tiers

Mode Execution

`scan`
(default)

`links`

`check <path>`

`drift <path>`

`cross-doc`

`report`

`claude-md`

`onboard`

`setup`

Automation Integration

Severity Levels

Output Rules

Lane Discipline

References