doc-update

Documentation Update

When to Use

• After making code changes that affect documented behavior
• During periodic documentation maintenance
• When onboarding reveals gaps or inaccuracies in docs
• Before a release to ensure docs match the current state
• When users report confusing or incorrect documentation

Prerequisites

• Access to the project's documentation files (README, docs/, wiki)
• Understanding of recent code changes or current behavior
• Ability to run the project to verify documented examples

Workflow

1. Inventory Existing Documentation

# Find all documentation files
glob pattern="**/*.md"

# Find inline documentation (JSDoc, docstrings)
grep -rn "/\*\*" src/ --include="*.ts" | Measure-Object -Line
grep -rn '"""' src/ --include="*.py" | Measure-Object -Line

# List docs by last modified date
Get-ChildItem -Recurse -Include *.md | Sort-Object LastWriteTime | Select-Object LastWriteTime, FullName

2. Identify Stale Documentation

# Find docs that reference renamed or deleted files
grep -rn "import.*from\|require(" docs/ --include="*.md" 2>$null

# Find docs referencing old function names or APIs
grep -rn "function_name\|ClassName\|/api/v1" docs/ --include="*.md"

# Compare documented CLI flags with actual implementation
grep -rn "\-\-[a-z]" README.md | Select-Object -First 20

Use the explore agent for deeper analysis:

task agent_type: "explore"
prompt: "Compare the README.md setup instructions with the actual package.json scripts and config files. Identify any mismatches."

3. Update Content

For each stale section:

1. Read the current code to understand actual behavior
2. Update the doc to match reality using edit
3. Test any code examples to verify they work

# Verify a documented command still works
npm run documented-command 2>&1 | Select-Object -First 5

4. Check Links

# Find all markdown links
grep -rn "\[.*\](.*)" docs/ --include="*.md" | Select-String "http"

# Find internal links and verify targets exist
grep -rn "\[.*\](\./\|\.\./" docs/ --include="*.md"