Docs update
Audit and maintain documentation quality using smart staleness checks. Use when reviewing or fixing documentation.From its SKILL.md
npx -y skills add parhumm/jaan-to --skill docs-updateAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
What its file declares
Copied from the file, not written here
The file declares its own license as PROPRIETARY. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.
SKILL.md
12.6 KB, as published. Nobody here has run it
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)
| Code Path | Related Doc |
|---|---|
skills/{name}/SKILL.md | $JAAN_DOCS_DIR/skills/{role}/{slug}.md |
$JAAN_LEARN_DIR/{name}.learn.md | (referenced in skill doc) |
$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 |
$JAAN_CONTEXT_DIR/boundaries.md | $JAAN_DOCS_DIR/config/boundaries.md |
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
| 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 |
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:
-
List all
.mdfiles in the same directory (excluding README.md itself) -
Parse the "## Available Skills" table rows in the README
-
Compare and flag:
- MISSING:
.mdfile exists in directory but not listed in Available Skills table - PHANTOM: Listed in table but
.mdfile doesn't exist in directory - STALE DESCRIPTION: Description in table differs significantly from the skill's SKILL.md
description:field
- MISSING:
-
Also check
$JAAN_DOCS_DIR/skills/README.mdroot 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
- Compare against actual
-
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:
| Overlap | Action |
|---|---|
| >80% | Flag for consolidation |
| 50-80% | Suggest differentiation |
| <50% | Keep separate |
Location Check
Verify docs are in correct folders:
| Content Type | Correct Location |
|---|---|
| Skill docs | $JAAN_DOCS_DIR/skills/{role}/ |
| Hook docs | $JAAN_DOCS_DIR/hooks/ |
| Config docs | $JAAN_DOCS_DIR/config/ |
| Guides | $JAAN_DOCS_DIR/extending/ |
Step 2.2: Compile Issues
Categorize findings:
| Category | Icon | Description |
|---|---|---|
| Healthy | ✅ | No issues |
| Need Updates | ⚠️ | Minor fixes needed |
| Deprecated | 🔴 | Archive candidate |
| Duplicates | 📦 | Consolidation needed |
| Misplaced | 📁 | Wrong location |
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
- Read both documents
- Merge best content into primary
- Archive the duplicate
- 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 <[email protected]>"
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
- NEVER delete without approval (archive instead)
- ALWAYS preserve content when consolidating
- ASK before major changes
- SKIP generated files (jaan-to/)
- BACKUP before bulk operations
- 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