Smart documentation management for creating and updating project documentation
I'll intelligently manage your project documentation by analyzing what actually happened and updating ALL relevant docs accordingly.
Target: 60% reduction (3,000-5,000 → 1,200-2,000 tokens)
1. Glob-First Documentation Discovery (95% savings)
# Discover all documentation without reading content
docs/
├── README.md
├── CHANGELOG.md
├── CONTRIBUTING.md
├── docs/
│ ├── API.md
│ ├── architecture.md
│ └── guides/
# Result: 100-200 tokens vs 5,000+ tokens reading all files
2. Git Diff-Driven Documentation Updates (80% savings)
# Detect which code changed to target documentation updates
git diff main...HEAD --name-only --diff-filter=AM
# Only read/update docs related to changed code areas:
# - src/api/* changed → Update API.md only
# - tests/* added → Update testing guide
# - No changes → Early exit, save 95%
# Result: 500-1,000 tokens vs 4,000+ tokens updating everything
3. Documentation Framework Detection Caching (70% savings)
# Cache detected documentation framework on first run
CACHE_FILE=".claude/cache/docs/framework.json"
{
"framework": "JSDoc",
"structure": {
"api": "docs/API.md",
"architecture": "docs/architecture.md",
"changelog": "CHANGELOG.md"
},
"conventions": {
"style": "keep-a-changelog",
"versioning": "semver"
},
"last_checksum": "a1b2c3d4"
}
# Subsequent runs: Read cache (50 tokens) vs analyzing structure (2,000 tokens)
4. Template-Based Documentation Generation (60% savings)
# Generate docs from templates rather than analyzing from scratch
TEMPLATES=".claude/cache/docs/templates/"
# Available templates:
# - API endpoint documentation
# - Function/method documentation (JSDoc, Sphinx, GoDoc)
# - Configuration option documentation
# - Migration guide structure
# - Troubleshooting section templates
# Result: 300-500 tokens template application vs 2,000+ tokens generation
5. Incremental Documentation Updates (70% savings)
# Update only changed sections, not full regeneration
# Read existing doc → Find section → Update in-place
# Example: Update single API endpoint
Old approach: Regenerate entire API.md (3,000 tokens)
Optimized: Update one section (500 tokens)
# Use Edit tool with precise old_string matching
# Preserve existing content, formatting, custom sections
6. Grep for Undocumented Exports (85% savings)
# Find undocumented code without reading all files
# Pattern-based discovery of documentation gaps
# TypeScript/JavaScript
rg "^export (function|class|interface|type)" --glob "src/**/*.ts" \
| grep -v "@param\|@returns\|/\*\*"
# Python
rg "^def |^class " --glob "**/*.py" \
| grep -v '"""'
# Result: 200-400 tokens Grep vs 3,000+ tokens reading all source files
7. Early Exit on Current Documentation (95% savings)
# Check if documentation needs updating before proceeding
check_docs_freshness() {
CACHE_FILE=".claude/cache/docs/last-update.json"
# Compare timestamps and checksums
LAST_UPDATE=$(jq -r '.timestamp' "$CACHE_FILE")
LAST_COMMIT=$(git log -1 --format=%ct)
if [ "$LAST_UPDATE" -ge "$LAST_COMMIT" ]; then
echo "✓ Documentation is current (updated after last commit)"
exit 0 # Save 95% tokens
fi
}
# Result: 100 tokens early exit vs 2,000+ tokens updating
8. Focus Area Flags for Targeted Updates (70% savings)
# Update specific documentation areas only
docs --readme # Update README only (600-1,200 tokens)
docs --changelog # Update CHANGELOG only (400-800 tokens)
docs --api # Update API docs only (1,000-2,000 tokens)
docs --architecture # Update architecture docs only (800-1,500 tokens)
# vs full update: 3,000-5,000 tokens
Cache Location: .claude/cache/docs/
Cached Artifacts:
{
"docs/inventory.json": {
"files": ["README.md", "CHANGELOG.md", "docs/API.md"],
"structure": { "api": "docs/API.md", "changelog": "CHANGELOG.md" },
"last_scan": "2026-01-27T10:30:00Z"
},
"docs/framework.json": {
"framework": "JSDoc",
"conventions": { "style": "keep-a-changelog", "versioning": "semver" },
"structure_checksum": "a1b2c3d4"
},
"docs/last-update.json": {
"timestamp": 1706352600,
"updated_files": ["README.md", "docs/API.md"],
"last_commit": "abc123def"
},
"docs/templates/": {
"api-endpoint.md": "...",
"function-jsdoc.tpl": "...",
"changelog-entry.md": "..."
}
}
Cache Invalidation:
Shared Caches:
/understand - Project structure and architecture analysis/readme-generate - README templates and project metadata/changelog-auto - Version history and commit patterns/inline-docs - Documentation framework detection (JSDoc/Sphinx/GoDoc)Operation: Overview Mode (Default)
├── Check cache validity (50 tokens)
├── Glob documentation files (100 tokens)
├── Read cache inventory (50 tokens)
├── Generate overview report (600 tokens)
└── Total: 800-1,500 tokens (vs 3,500-5,000 unoptimized)
Operation: Smart Update Mode
├── Git diff to detect changes (100 tokens)
├── Check docs freshness cache (50 tokens)
├── Identify affected docs (100 tokens)
├── Read only affected sections (500-1,000 tokens)
├── Apply template-based updates (400-600 tokens)
├── Update cache (50 tokens)
└── Total: 1,200-2,000 tokens (vs 4,000-7,000 unoptimized)
Operation: Focused Update (--readme, --changelog, etc.)
├── Read cache for structure (50 tokens)
├── Read specific file only (200-400 tokens)
├── Apply targeted update (300-500 tokens)
├── Update cache (50 tokens)
└── Total: 600-1,200 tokens (vs 2,000-3,500 unoptimized)
Operation: Early Exit (Docs Current)
├── Check last update timestamp (50 tokens)
├── Compare with git log (50 tokens)
├── Exit with "docs current" message (100 tokens)
└── Total: 200 tokens (95% savings vs full update)
Optimized Usage:
# Overview with minimal tokens
docs # 800-1,500 tokens (Glob + cache)
# Targeted updates
docs update # 1,200-2,000 tokens (git diff driven)
docs --readme # 600-1,200 tokens (README only)
docs --changelog # 400-800 tokens (CHANGELOG only)
docs --api # 1,000-2,000 tokens (API docs only)
docs --architecture # 800-1,500 tokens (architecture only)
# After session work
docs update # 1,500-2,500 tokens (session context)
# Force refresh (bypass cache)
docs --no-cache # 3,000-5,000 tokens (full analysis)
| Technique | Token Savings | When Applied |
|---|---|---|
| Glob-first discovery | 95% | All documentation discovery |
| Git diff targeting | 80% | Update operations |
| Framework detection cache | 70% | First-time analysis (cached thereafter) |
| Template-based generation | 60% | Doc creation/updates |
| Incremental updates | 70% | Section modifications |
| Grep undocumented code | 85% | Gap analysis |
| Early exit | 95% | When docs current |
| Focus area flags | 70% | Targeted updates |
Before Optimization:
After Optimization:
Synergy with other optimized skills:
/understand cache → Reuse architecture analysis (saves 2,000-4,000 tokens)/changelog-auto → Share version history cache (saves 500-1,000 tokens)/readme-generate → Share project metadata cache (saves 800-1,500 tokens)/inline-docs → Share framework detection (saves 600-1,200 tokens)/commit → Trigger docs update after commits (smart context)My approach:
I won't make assumptions - I'll look at what ACTUALLY changed and update accordingly. If you refactored the entire architecture, I'll update architecture docs, README, migration guides, API docs, and anything else affected.
When you run /docs without context, I'll:
Output format:
DOCUMENTATION OVERVIEW
├── README.md - [status: current/outdated]
├── CHANGELOG.md - [last updated: date]
├── CONTRIBUTING.md - [completeness: 85%]
├── docs/
│ ├── API.md - [status]
│ └── architecture.md - [status]
└── Total coverage: X%
KEY FINDINGS
- Missing: Setup instructions
- Outdated: API endpoints (3 new ones)
- Incomplete: Testing guide
When you run /docs update or after implementations, I'll:
Run /understand to analyze current codebase
Compare code reality vs documentation
Identify what needs updating:
Update systematically:
When run after a long coding session, I'll:
Updates will follow your project's documentation style and conventions, organizing changes by type (Added, Fixed, Changed, etc.) in the appropriate sections.
Based on what happened in session:
Works seamlessly with:
/understand - Get current architecture first/contributing - Update contribution guidelines/test - Document test coverage changes/scaffold - Add new component docs/security-scan - Update security documentationALWAYS:
Preserve sections:
<!-- CUSTOM:START -->
User's manual content preserved
<!-- CUSTOM:END -->
Smart CHANGELOG:
Important: I will NEVER:
After analysis, I'll ask: "How should I proceed?"
Simply run /docs after any significant work:
/understand - Ensure docs match code reality/fix-todos or bug fixes - Update all affected documentation/scaffold or new features - Document what was added/security-scan or /review - Document findings and decisionsI'll figure out what needs updating based on what actually happened, not rigid rules.
I can manage:
After analyzing code:
/understand && /docs
# Analyzes entire codebase, then updates docs to match reality
After fixing technical debt:
/fix-todos && /test && /docs
# Fixes TODOs, verifies everything works, documents changes
After major refactoring:
/fix-imports && /format && /docs
# Fixes imports, formats code, updates architecture docs
Before creating PR:
/review && /docs
# Reviews code, then ensures docs reflect any issues found
After adding features:
/scaffold component && /test && /docs
# Creates component, tests it, documents the new API
Just run /docs and I'll figure out what you need:
No need to remember arguments - I understand context!
This keeps your documentation as current as your code while supporting your entire development lifecycle.
