/docs-update

Smart documentation auditing with git-based staleness detection.

---

What It Does

Default (no args): Uses git history to find docs that are out of sync with their source code. Compares when code changed vs when docs were last updated.

Full audit: Scans all docs for quality issues, checks frontmatter, structure, links, duplicates, and STYLE.md compliance.

---

Usage

/docs-update [path] [--full] [--fix] [--check-only] [--quick]

Argument	Effect
(none)	Smart default: staleness check
[path]	Check specific path only
--full	Skip staleness, do full audit
--fix	Auto-fix issues
--check-only	Report only, no changes
--quick	Inventory only

---

How It Maps Code to Docs

Code Path	Related Doc
skills/{name}/	$JAAN_DOCS_DIR/skills/{role}/{slug}.md
$JAAN_CONTEXT_DIR/hooks/{name}.sh	$JAAN_DOCS_DIR/hooks/{name}.md
$JAAN_CONTEXT_DIR/config.md	$JAAN_DOCS_DIR/config/README.md
$JAAN_CONTEXT_DIR/*.md	$JAAN_DOCS_DIR/config/context.md

---

What It Checks (Full Audit)

Check	Description
Frontmatter	Valid YAML with required fields
Structure	H1, tagline, separators
Line limits	Under max for doc type
Links	Internal links valid
Duplicates	Similar content detected
Location	File in correct folder

---

Output: Staleness Report (Default)

# Documentation Staleness Report
**Code changes:** 5 files | **Docs checked:** 12

## Potentially Outdated
| Doc | Related Code | Delta |
|-----|--------------|-------|
| $JAAN_DOCS_DIR/skills/pm/prd-write.md | pm-prd-write/SKILL.md | 15d stale |

## Missing Documentation
| Code File | Expected Doc |
|-----------|--------------|
| new-skill/SKILL.md | $JAAN_DOCS_DIR/skills/?/new-skill.md |

[1] Review stale  [2] Full audit  [3] Quick fix  [4] Exit

---

Output: Full Audit Report

# Documentation Audit Report
**Files:** 21 | **Issues:** 5

## Summary
| Category | Count |
|----------|-------|
| ✅ Healthy | 16 |
| ⚠️ Need Updates | 3 |
| 🔴 Deprecated | 1 |
| 📦 Duplicates | 1 |

## Priority Actions
1. **hooks/old-hook.md** - Deprecated - Archive
2. **config/settings.md** - Missing frontmatter - Fix

---

Example

Smart staleness check (default):

/docs-update

Full audit:

/docs-update --full

Full audit with auto-fix:

/docs-update --full --fix

Check specific path:

/docs-update $JAAN_DOCS_DIR/skills/ --check-only

---

Fixes Applied

Issue	Auto-Fix
Missing frontmatter	Adds with defaults
Missing dates	Adds current date
Missing separators	Adds ---
H4+ headings	Converts to H3
Deprecated docs	Archives to $JAAN_DOCS_DIR/archive/
Broken links	Reports with suggestions
Duplicates	Suggests consolidation

---

Tips

• Run without args for smart staleness detection
• Use --full when you want comprehensive quality checks
• Staleness threshold is 7 days (code changed > 7d before doc)
• Deprecated docs are archived, never deleted
• Updates updated_date on all modified files