Doc Review Skill

Systematically review documentation for staleness, accuracy, and relevance.

The Job

• Scan all documentation files

• Check for staleness indicators

• Verify referenced code/files still exist

• Identify outdated content

• Generate cleanup report

• Optionally apply fixes

When to Use

Scheduled

• After each milestone completion

• Monthly maintenance cycle

• Before major releases

On Demand

• When documentation feels outdated

• After significant refactoring

• When onboarding reveals confusion

Review Process

Step 1: Inventory Documentation

Scan for documentation files:

find . -name ".md" -not -path "./.git/" -not -path "./.vendor/" -not -path "./.worktrees/"

Common locations:

• README.md (root and subdirs)

• docs/ directory

• AGENTS.md , CLAUDE.md

• .claude/skills/*/SKILL.md

• knowledge/ directory

• scripts/aha-loop/templates/

Step 2: Check Staleness Indicators

For each document, check:

Indicator Check Method Threshold

Last modified git log -1

30 days

Referenced files grep + verify Missing = stale

Code examples Syntax check Errors = stale

Version numbers Compare to actual Mismatch = stale

Links HTTP check Broken = stale

Step 3: Verify Code References

For each code reference in docs:

Code Reference Check

File: [doc-path] Reference: src/main.rs:45-60 Status: [Exists | Missing | Changed]

If Changed:

• Original: [what doc says]
• Current: [what code shows]
• Action: [Update doc | Flag for review]

Step 4: Check External Links

Extract URLs

grep -oP 'https?://[^\s)]+' file.md

Check each URL

curl -s -o /dev/null -w "%{http_code}" URL

Step 5: Generate Report

Create docs-review-report.md :

Documentation Review Report

Date: [YYYY-MM-DD] Reviewed: [N] files Issues Found: [N]

Summary

Issues by File

[file1.md]

• Line 45: Reference to src/old.rs - file no longer exists
• Line 78: Code example uses deprecated API

[file2.md]

• Line 12: Version "1.0.0" should be "2.0.0"
• Line 56: Broken link to external docs

Recommended Actions

1. Delete: [files that should be removed]
2. Update: [files that need content updates]
3. Review: [files that need human review]

Auto-fixable

The following can be auto-fixed:

• Update version numbers
• Remove dead links
• Update file paths

Run ./scripts/aha-loop/doc-cleaner.sh --fix to apply.

Staleness Criteria

Definitely Stale

• References files that don't exist

• Contains code that doesn't compile

• Links to 404 pages

• Describes features that were removed

Probably Stale

• Not modified in 60+ days

• Uses old API patterns

• References old version numbers

• No recent git commits mention the file

Needs Human Review

• Contains outdated but complex content

• Describes deprecated but still-supported features

• Historical documentation (changelogs, decisions)

Auto-Fix Rules

Safe to Auto-Fix

• Update file paths (if clear mapping exists)

• Remove broken external links

• Update version numbers in dependency lists

• Fix obvious typos in code references

Requires Human Review

• Content changes beyond mechanical updates

• Removing entire sections

• Changing technical instructions

• Modifying architecture decisions

Integration

With Doc Cleaner Script

Generate report only

./scripts/aha-loop/doc-cleaner.sh --report

Apply safe fixes

./scripts/aha-loop/doc-cleaner.sh --fix

Interactive mode

./scripts/aha-loop/doc-cleaner.sh --interactive

With Observability

Log review activities:

2026-01-29 16:00:00 | Task: Maintenance | Phase: Doc Review

Documentation Review

Scanned 45 files, found 7 issues.

Key Findings

• AGENTS.md references outdated skill paths
• README example code uses deprecated API

Actions Taken

• Auto-fixed 3 version number issues
• Flagged 4 items for human review

Checklist

Before completing review:

• All markdown files scanned

• Code references verified

• External links checked

• Report generated

• Auto-fixes applied (if safe)

• Human review items flagged

Example Review

Input

File: docs/api.md last modified 90 days ago

API Documentation

Authentication

See src/auth/mod.rs for implementation.

Use version 0.5.0 of the auth library:

auth-lib = "0.5.0"

More info: https://example.com/old-docs

### Review Findings

1. **Stale**: Last modified 90 days ago
2. **Missing Reference**: `src/auth/mod.rs` doesn't exist (moved to `src/api/auth.rs`)
3. **Outdated Version**: Current version is 1.2.0, not 0.5.0
4. **Broken Link**: https://example.com/old-docs returns 404

### Report Entry

```markdown
### docs/api.md

**Staleness:** 90 days since last update
**Issues:**
- [ ] Line 5: `src/auth/mod.rs` → `src/api/auth.rs`
- [ ] Line 8: Version 0.5.0 → 1.2.0
- [ ] Line 12: Broken link (404)

**Recommendation:** Update file paths and versions, remove broken link

Prevention

To reduce future staleness:

- Update docs with code - When changing code, update related docs

- Add doc checks to CI - Fail on broken references

- Schedule regular reviews - Monthly or per-milestone

- Use relative links - Easier to maintain than absolute

- Date-stamp examples - "As of v1.2.0"