docs-freshness-audit

Original：🇨🇳 Chinese

Translated

Periodically audit a repository's docs for staleness against the implementation: run a cheap mechanical scan (dead source-path references, dead links, leftover DEPRECATED/TBD banners, doc-vs-code freshness gap, git-invisible ignored leftovers, completed-but-undeleted plan files), then dispatch parallel read-only agents to verify only the suspicious docs against source, and finally propose update / delete / migrate-to-ADR dispositions for user approval. Use on a monthly or quarterly docs review, after large refactors or renames, or when asked whether docs are stale.

8installs

Sourcenextaltair/altairs-agent-dev-kit

Added on2026-09-05

NPX Install

npx skill4agent add nextaltair/altairs-agent-dev-kit docs-freshness-audit

SKILL.md Content (Chinese)

View Translation Comparison →

Docs Freshness Audit

A step-by-step guide to auditing whether docs diverge from implementation, leading to dispositions of "Update / Delete / Migrate to ADR". Leaving behind specification documents with banners, specs that continue to describe non-existent modules, or plan files that remain even after being merged will actually cause confusion.

Step 0: Confirm Deployment Settings

The skill itself only contains procedures and prompts. Start by gathering the following from the deployment's CLAUDE.md / rules / documentation maintenance policy (confirm with the user if missing):

Item	Example
Docs Validation Command	`make docs-okf` , `python scripts/validate_docs.py`
Audit Exclusions	Bundles like ADR/design (delegated to respective management rules), generated artifacts
Plan/Design Output Directories	`docs/plans/` , `docs/superpowers/plans
Maintenance History Entry Location	`docs/documentation-maintenance.md`
Deletion Operation Rules	Push rules for docs chores (whether direct push is allowed)

Phase 1: Mechanical Scan (Low Cost, Run Every Time)

Each scan is completed with bash. Aggregate results into a "List of Suspicious Files (with Reasons)".

Dead Source Path References: Extract source-path-like strings from docs and check if they exist

bash

git ls-files docs | grep "\.md$" | while read doc; do
  grep -oE "src/[A-Za-z0-9_/.-]+\.[a-z]+" "$doc" | sort -u | while read p; do
    [ -e "$p" ] || echo "$doc -> $p"
  done
done

Dead Internal Links: Check if the targets of markdown relative links (
```
](path)
```
) exist
Self-Reported Banner Detection: Grep for
```
DEPRECATED
```
/
```
Superseded
```
/
```
Needs Confirmation
```
/
```
TBD
```
/
```
Unresolved
```
/
```
Confirmation Items
```
. Documents left with banners are flagged as suspicious as "known sources of confusion"

Freshness Gap: Compare the last commit date of the doc with the recent churn of the code it describes

bash

git log -1 --format=%ad --date=short -- "$doc"   # doc side
git log --since="$doc_date" --oneline -- "$src_area" | wc -l   # code side divergence amount

Git-Invisible Leftovers: List ignored/untracked files in the audit target tree. Since
```
git rm
```
only deletes tracked files, artifacts that were intended to be deleted may remain on disk
bash
```
git status --ignored --porcelain docs/ | grep "^!!\|^??"
```
Unremoved Plan Files: Extract Issue/PR numbers from each file in the plan output directory and check their status with
```
gh
```
. If all are closed/merged, mark as candidates for deletion as "leftover completed plans". Plans without issue/PR references are flagged as suspicious based on elapsed days and sent to Phase 2
bash
```
grep -oE "#[0-9]+" "$plan" | sort -u | while read n; do
  gh issue view "${n#\#}" --json state --jq .state 2>/dev/null \
    || gh pr view "${n#\#}" --json state --jq .state
done
```

Phase 2: Semantic Audit (Suspicious Files Only, Parallel Read-Only Agents)

Dispatch parallel read-only agents to compare docs vs. implementation for the suspicious files from Phase 1. Mechanical scans cannot detect discrepancies like "describing an unused old algorithm as correct", so this phase should not be skipped (during deep audits).

Prompt Template:

In <repo>, please audit the discrepancies between document <doc> (last updated <date>) and the current implementation.

Steps:
1. Read the entire <doc>
2. Verify the modules/classes/functions/widgets mentioned in the doc against the current <src candidates>
3. List discrepancies: (a) elements written in the doc that do not exist in the implementation,
   (b) major elements present in the implementation but missing from the doc, (c) mismatches in names, signatures, or algorithms
4. Check for the existence of live documents (<live doc candidates>) that can cover the same area

Output: Bullet points of discrepancies (doc line number + implementation file:line). Finally, provide one judgment:
"Generally Accurate / Partial Correction Sufficient / Full Rewrite Needed / Can Be Deleted (Covered by Live Docs)" + 1-2 sentences of rationale.

Note: Re-verify agent reports of "not referenced" to check if the files are tracked or ignored (there are actual cases where artifacts were mistakenly thought to be untracked but were actually tracked by git).

Phase 3: Disposition and Execution (User Approval Gate Required)

Decision Matrix:

Status	Disposition
Live docs/implementation already cover the same area, no unique value	Delete (git history will preserve it)
Describes current functionality but is outdated	Update (reflect implementation verification results)
Only valuable as a record of design decisions	Migrate to ADR and delete the original
Matches implementation	Maintain with an audit confirmation note (dated)
Completed plan file	Delete

Present the candidate list with reasons to the user, and execute only after obtaining approval (do not delete without permission). Grouping candidates (definite deletions / requires judgment / local only) and asking for multiple selections speeds up the process
After execution, run the verification command from Step 0 and leave an audit record (what was deleted/modified and why) in the maintenance history
Do not delete the tool's default output destinations (such as directories automatically written to by the skill) even if they look cluttered — the tool will regenerate them anyway. Instead, clearly define role responsibilities in the documentation maintenance policy

Execution Modes

Light Audit (Monthly Guideline): Phase 1 only → If no suspicious items, record and finish; if any, report
Deep Audit (Quarterly Guideline / After Large Refactors or Renames): Full set of Phase 1 + 2 + 3

The frequency is left to the deployment's operations (e.g., initiated by a person in the same framework as monthly dependency reviews).