Help us improve
Share bugs, ideas, or general feedback.
From jaan-to
Audits documentation against source code using git-based staleness detection. Run with no args for smart check or specify a path. Supports full audit, auto-fix, and check-only modes.
npx claudepluginhub parhumm/jaan-to --plugin jaan-toHow this skill is triggered — by the user, by Claude, or both
Slash command
/jaan-to:docs-update [path] [--full] [--fix] [--check-only] [--quick][path] [--full] [--fix] [--check-only] [--quick]This skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
> Smart documentation auditing with git-based staleness detection.
Audits repository documentation for drift, stale statements, broken references, and README mismatches before corrective PRs.
Spawns a doc-maintainer agent to audit all project documentation for correctness, completeness, freshness, and consistency. It autonomously fixes issues like typos, stale code examples, and broken links, surfacing anything requiring user approval.
Audits codebase documentation for accuracy, completeness, and freshness by comparing against code structure. Auto-fixes small discrepancies in fix mode, reports structural changes. Works with any language/framework.
Share bugs, ideas, or general feedback.
Smart documentation auditing with git-based staleness detection.
${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 protocolNote: 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.
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:
$JAAN_LEARN_DIR/jaan-to-docs.learn.md (fallback: ${CLAUDE_PLUGIN_ROOT}/skills/docs-create/LEARN.md)$JAAN_TEMPLATES_DIR/jaan-to-docs.template.md (fallback: ${CLAUDE_PLUGIN_ROOT}/skills/docs-create/template.md)Read and apply language protocol: ${CLAUDE_PLUGIN_ROOT}/docs/extending/language-protocol.md
Override field for this skill: language_docs-update
| 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)
Goal: Find docs that are out of sync with their source code.
Trigger: Run with NO arguments or just --fix
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)
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.
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
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
# Check if expected doc exists
git ls-files -- {expected_doc_path}
If code exists but doc doesn't → Flag as MISSING
# 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.
Goal: Understand documentation state without reading everything.
Trigger: --full, [path] argument, or user chose Option 2 from staleness report
Use Glob to count docs (don't read all):
Glob: $JAAN_DOCS_DIR/**/*.md
Exclude: node_modules/
git log --since="30 days ago" --oneline --name-only -- $JAAN_DOCS_DIR/ | head -30
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
## 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.
Load files one at a time to save tokens. For each file, check:
---
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)
---
> description)---Check all internal links:
[text](path.md) - file exists?[text](../path.md) - relative path valid?For each $JAAN_DOCS_DIR/skills/{role}/README.md:
List all .md files in the same directory (excluding README.md itself)
Parse the "## Available Skills" table rows in the README
Compare and flag:
.md file exists in directory but not listed in Available Skills table.md file doesn't exist in directorydescription: fieldAlso check $JAAN_DOCS_DIR/skills/README.md root Available Roles table:
$JAAN_DOCS_DIR/skills/*/ subdirectories that contain filesReport findings in the audit report under a "## README Index Consistency" section
Auto-fix logic (Phase 3):
Compare similar docs for overlap:
| Overlap | Action |
|---|---|
| >80% | Flag for consolidation |
| 50-80% | Suggest differentiation |
| <50% | Keep separate |
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/ |
Categorize findings:
| Category | Icon | Description |
|---|---|---|
| Healthy | ✅ | No issues |
| Need Updates | ⚠️ | Minor fixes needed |
| Deprecated | 🔴 | Archive candidate |
| Duplicates | 📦 | Consolidation needed |
| Misplaced | 📁 | Wrong location |
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.
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."
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]
---
--- separatorsFor any modified file:
updated_date: {today}
git mv $JAAN_DOCS_DIR/wrong-location/file.md $JAAN_DOCS_DIR/correct-location/
Update any references to moved file.
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>"
✅ 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}
"No documentation files found in
{path}."
"Cannot modify
{file}. Check permissions."
"Git not available. Changes saved but not committed."