Documentation is current

Severity: Recommended

Check automatically:

1. Check doc file freshness:

# Last modified dates for docs (macOS)
find docs/ -name "*.md" -exec stat -f "%m %N" {} \; 2>/dev/null | sort -rn | head -10

# Linux:
find docs/ -name "*.md" -printf "%T@ %p\n" 2>/dev/null | sort -rn | head -10

2. Look for staleness signals:

# Find TODO/outdated markers in docs
grep -riE "TODO|FIXME|outdated|update.?this|needs.?update" docs/ *.md 2>/dev/null

3. Spot-check: compare doc age to referenced file changes:

# Get last commit date for a doc file
git log -1 --format="%ci" -- docs/payments.md

# Extract file paths mentioned in the doc
grep -oE '[a-zA-Z0-9_/]+\.(ts|js|py|rb|go)' docs/payments.md | sort -u

# Check if any referenced files changed AFTER the doc
git log -1 --format="%ci" -- src/payments/checkout.ts

If referenced source files have commits newer than the doc file, the doc may be stale.

4. Automated staleness detection:

# For each doc, find referenced files and compare dates
# Flag if source file changed after doc was last updated

Ask user:

• When were docs last reviewed/updated?
• Any known stale documentation?

Pass criteria:

• Docs modified within reasonable timeframe relative to code changes
• No obvious staleness markers (TODO, outdated)
• Referenced source files have not changed significantly since doc was last updated

Fail criteria:

• Docs untouched for 6+ months while referenced code actively changed
• Docs describe features/files that no longer exist
• Source files referenced in docs changed substantially after doc's last update

Evidence to capture:

• Last modified dates for key doc files
• Staleness markers found
• Spot-check results: docs vs referenced file commit dates

---