docs-update

Smart documentation auditing with git-based staleness detection.

Context Files

• ${CLAUDE_PLUGIN_ROOT}/docs/STYLE.md - Documentation standards (read from plugin source)
• $JAAN_TEMPLATES_DIR/jaan-to-docs.template.md - Shared docs template (shared with docs-create)
• $JAAN_LEARN_DIR/jaan-to-docs.learn.md - Shared docs lessons (shared with docs-create, loaded in Pre-Execution)
• ${CLAUDE_PLUGIN_ROOT}/docs/extending/language-protocol.md - Language resolution protocol

Note: STYLE.md is read from the plugin source. Templates are read from $JAAN_TEMPLATES_DIR. Pre-execution protocol Step C offers to seed from the plugin on first use.

Pre-Execution Protocol

MANDATORY — Read and execute ALL steps in: ${CLAUDE_PLUGIN_ROOT}/docs/extending/pre-execution-protocol.md Skill name: docs-update Execute: Step 0 (Init Guard) → A (Load Lessons) → B (Resolve Template) → C (Offer Template Seeding) Shared resource override: Template and learn files are shared with docs-create. For Steps A/B/C, resolve using docs as the resource name:

• Learn: $JAAN_LEARN_DIR/jaan-to-docs.learn.md (fallback: ${CLAUDE_PLUGIN_ROOT}/skills/docs-create/LEARN.md)
• Template: $JAAN_TEMPLATES_DIR/jaan-to-docs.template.md (fallback: ${CLAUDE_PLUGIN_ROOT}/skills/docs-create/template.md)

Language Settings

Read and apply language protocol: ${CLAUDE_PLUGIN_ROOT}/docs/extending/language-protocol.md Override field for this skill: language_docs-update

File Mapping (Code → Docs)

Slug extraction: pm-prd-write → prd-write (remove role prefix)

PHASE 0: Smart Default - Staleness Detection

Goal: Find docs that are out of sync with their source code.

Trigger: Run with NO arguments or just --fix

Step 0.1: Parse Arguments

Arguments: $ARGUMENTS

If --full or [path] provided: Skip to PHASE 1 (Quick Inventory)

Step 0.2: Get Recent Code Changes

git log --since="30 days ago" --name-only --pretty=format: -- skills/ $JAAN_CONTEXT_DIR/hooks/ $JAAN_CONTEXT_DIR/config.md $JAAN_CONTEXT_DIR/ | sort -u | grep -v '^$'

Extract unique changed files.

Step 0.3: Map Code Files to Docs

For each changed code file, find related doc:

Skills:

skills/{name}/SKILL.md → $JAAN_DOCS_DIR/skills/{role}/{slug}.md

# Extract slug: remove brand prefix and role
# pm-prd-write → prd-write
# learn-add → learn-add (core role)

Hooks:

$JAAN_CONTEXT_DIR/hooks/{name}.sh → $JAAN_DOCS_DIR/hooks/{name}.md

Config:

$JAAN_CONTEXT_DIR/config.md → $JAAN_DOCS_DIR/config/README.md
$JAAN_CONTEXT_DIR/*.md → $JAAN_DOCS_DIR/config/context.md
$JAAN_CONTEXT_DIR/boundaries.md → $JAAN_DOCS_DIR/config/boundaries.md

Step 0.4: Compare Timestamps

For each code→doc pair:

# Get code last modified
git log -1 --format=%ai -- {code_path}

# Get doc last modified
git log -1 --format=%ai -- {doc_path}

Staleness threshold: 7 days

• If code_date > doc_date + 7 days → Flag as STALE

Step 0.5: Check for Missing Docs

# Check if expected doc exists
git ls-files -- {expected_doc_path}

If code exists but doc doesn't → Flag as MISSING

Step 0.6: Generate Staleness Report

# Documentation Staleness Report
**Date:** {date} | **Code changes:** {n} files | **Docs checked:** {n}

## Potentially Outdated

| Doc | Related Code | Code Changed | Doc Updated | Delta |
|-----|--------------|--------------|-------------|-------|
| $JAAN_DOCS_DIR/skills/pm/prd-write.md | skills/pm-prd-write/SKILL.md | 2026-01-25 | 2026-01-10 | 15d stale |

## Missing Documentation

| Code File | Expected Doc | Action |
|-----------|--------------|--------|
| skills/new-skill/SKILL.md | $JAAN_DOCS_DIR/skills/?/new-skill.md | Create |

## Up to Date

✅ {n} docs are current (code and doc in sync)

---

What would you like to do?
[1] Review stale docs one by one
[2] Full audit (check everything)
[3] Quick fix (update dates only)
[4] Exit

HARD STOP: Wait for user choice.

Option 1: For each stale doc, show side-by-side what changed in code, ask what to update. Option 2: Continue to PHASE 1 (full audit). Option 3: Just update updated_date in stale docs. Option 4: Stop.

PHASE 1: Quick Inventory

Goal: Understand documentation state without reading everything.

Trigger: --full, [path] argument, or user chose Option 2 from staleness report

Step 1.1: Inventory Files

Use Glob to count docs (don't read all):

Glob: $JAAN_DOCS_DIR/**/*.md

Exclude: node_modules/

Step 1.2: Check Recent Doc Changes

git log --since="30 days ago" --oneline --name-only -- $JAAN_DOCS_DIR/ | head -30

Step 1.3: Quick Scan for Issues

Use Grep to detect problems without reading files:

Missing frontmatter:

Grep: "^---$" in $JAAN_DOCS_DIR/**/*.md (check first line)

Missing tagline:

Grep: "^>" in $JAAN_DOCS_DIR/**/*.md

Step 1.4: Generate Audit Proposal

## Documentation Audit Proposal

**Files found:** X docs
**Recent changes:** X files in last 30 days

### Quick Scan Results
- Missing frontmatter: X files
- Missing tagline: X files
- Potential issues: X files

Proceed with full audit? [yes/no/quick-fixes-only]

If --quick: Stop here. If "no": Stop here. If "quick-fixes-only": Only fix frontmatter/dates. If "yes": Continue to full audit.

PHASE 2: Full Analysis

Step 2.1: Progressive File Loading

Load files one at a time to save tokens. For each file, check:

Frontmatter Validation

---
title: Required
doc_type: Required (skill|hook|config|guide|concept|index)
created_date: Required (YYYY-MM-DD)
updated_date: Required (YYYY-MM-DD)
tags: Required (array)
---

Structure Validation

• Has H1 title (only one)
• Has tagline (> description)
• Sections separated with ---
• No H4+ headings
• Under line limit for type

Link Validation

Check all internal links:

• [text](path.md) - file exists?
• [text](../path.md) - relative path valid?

README Index Consistency

For each $JAAN_DOCS_DIR/skills/{role}/README.md:

1. List all .md files in the same directory (excluding README.md itself)

2. Parse the "## Available Skills" table rows in the README

3. Compare and flag:

   • MISSING: .md file exists in directory but not listed in Available Skills table
   • PHANTOM: Listed in table but .md file doesn't exist in directory
   • STALE DESCRIPTION: Description in table differs significantly from the skill's SKILL.md description: field

4. Also check $JAAN_DOCS_DIR/skills/README.md root Available Roles table:

   • Compare against actual $JAAN_DOCS_DIR/skills/*/ subdirectories that contain files
   • Flag roles with directories but missing from table as MISSING ROLE
   • Flag roles listed as "Planned" that have active skill docs as STALE STATUS

5. Report findings in the audit report under a "## README Index Consistency" section

Auto-fix logic (Phase 3):

• MISSING → add row to table using description from SKILL.md frontmatter
• PHANTOM → remove row or ask user for decision
• STALE DESCRIPTION → update description from SKILL.md
• MISSING ROLE → add row to root Available Roles table with "Active" status
• STALE STATUS → update "Planned" to "Active" in root table

Duplication Detection

Compare similar docs for overlap:

Location Check

Verify docs are in correct folders:

Step 2.2: Compile Issues

Categorize findings:

HARD STOP - Audit Report

Show audit report:

# Documentation Audit Report
**Date:** {date} | **Files:** {count} | **Issues:** {count}

## Summary
| Category | Count | Action |
|----------|-------|--------|
| ✅ Healthy | X | None |
| ⚠️ Need Updates | X | Update |
| 🔴 Deprecated | X | Archive |
| 📦 Duplicates | X | Consolidate |
| 📁 Misplaced | X | Move |

## Priority Actions

### High Priority
1. **{file}** - {issue} - {action}

### Medium Priority
2. **{file}** - {issue} - {action}

### Low Priority
3. **{file}** - {issue} - {action}

---

Apply fixes? [yes/no/selective]

If --check-only: Stop here. Do NOT proceed without explicit approval.

PHASE 3: Apply Fixes

Step 3.1: Archive Deprecated Docs

mkdir -p $JAAN_DOCS_DIR/archive
git mv $JAAN_DOCS_DIR/deprecated-file.md $JAAN_DOCS_DIR/archive/

Add note at top: "ARCHIVED: See [new-doc.md] for current information."

Step 3.2: Consolidate Duplicates

1. Read both documents
2. Merge best content into primary
3. Archive the duplicate
4. Update cross-references

Step 3.3: Fix Frontmatter

Add missing frontmatter:

---
title: [Inferred from H1]
doc_type: [Inferred from path]
created_date: [From git log or today]
updated_date: [Today]
tags: [Inferred from content]
---

Step 3.4: Fix Structure

• Add missing --- separators
• Convert H4+ to H3 or bullets
• Add missing tagline (ask user)

Step 3.5: Fix Links

• Report broken links with suggestions
• Update paths for moved files

Step 3.6: Update Dates

For any modified file:

updated_date: {today}

Step 3.7: Move Misplaced Files

git mv $JAAN_DOCS_DIR/wrong-location/file.md $JAAN_DOCS_DIR/correct-location/

Update any references to moved file.

PHASE 4: Commit & Report

Step 4.1: Commit Changes

Ask: "Commit documentation updates? [y/n]"

If yes:

git add $JAAN_DOCS_DIR/
git commit -m "docs: Audit and update documentation

- Fixed: X files
- Archived: X files
- Moved: X files

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>"

Step 4.2: Final Report

✅ Documentation audit complete!

## Changes Applied
- Fixed frontmatter: X files
- Fixed structure: X files
- Archived: X files
- Moved: X files
- Updated dates: X files

## Documentation Health: [EXCELLENT/GOOD/NEEDS WORK]

Commit: {hash}

Error Handling

No Docs Found

"No documentation files found in {path}."

Permission Denied

"Cannot modify {file}. Check permissions."

Git Not Available

"Git not available. Changes saved but not committed."

Trust Rules

1. NEVER delete without approval (archive instead)
2. ALWAYS preserve content when consolidating
3. ASK before major changes
4. SKIP generated files (jaan-to/)
5. BACKUP before bulk operations
6. PREVIEW all changes before applying

Skill Alignment

• Two-phase workflow with HARD STOP for human approval
• Single source of truth (no duplication)
• Plugin-internal automation
• Maintains human control over changes

Definition of Done

• Staleness check completed across all doc paths
• Stale or missing docs identified and reported
• Fixes applied (if --fix mode) or report generated (if --check-only)
• User approved changes