benjaminshoemaker/update-docs

Update Documentation

Automatically update documentation to reflect code changes. Enforces the "README as landing page" pattern—README should be a concise entry point, with detailed documentation in docs/.

Core Philosophy

"Your README is not your documentation. It is an overview of your project... a gateway to other pieces of info."

| README.md | docs/ | |-----------|-------| | What is this? Why should I care? | How does everything work? | | Quick start (copy-paste ready) | Step-by-step tutorials | | Minimal examples | Complete API/command reference | | Links to detailed docs | In-depth configuration | | < 300 lines ideal | As long as needed |

Trigger Modes

1. Post-commit (automatic): Triggered by git hook after commits
2. Manual with commit range: /update-docs HEAD~3..HEAD to analyze specific commits
3. Manual with working tree: /update-docs --working-tree to analyze uncommitted changes
4. Audit mode: /update-docs --audit to check README health and suggest migrations

Arguments

• No arguments: Analyze the most recent commit (HEAD)
• HEAD~N..HEAD: Analyze the last N commits
• COMMIT1..COMMIT2: Analyze a specific commit range
• --working-tree or -w: Analyze uncommitted changes in working tree
• --audit or -a: Audit README structure and suggest migrations to docs/

Marker File Detection

When triggered by post-commit hook, check for .claude/doc-update-pending.json:

if [ -f .claude/doc-update-pending.json ]; then
  COMMIT=$(jq -r '.commit_short' .claude/doc-update-pending.json)
fi

After processing, always clean up:

rm -f .claude/doc-update-pending.json

---

Workflow

Update Docs Progress:
- [ ] Phase 1: Discover and audit documentation structure
- [ ] Phase 2: Detect changes (git diff or working tree)
- [ ] Phase 3: Route updates to correct location
- [ ] Phase 4: Migrate bloated README sections (if needed)
- [ ] Phase 5: Apply updates
- [ ] Phase 6: Update CHANGELOG (if exists)
- [ ] Phase 7: Create docs commit (if changes made)

---

Phase 1: Discover and Audit Documentation Structure

1.1 Scan for Documentation Files

# Primary
README.md, AGENTS.md, CHANGELOG.md, CONTRIBUTING.md

# Secondary (docs/)
docs/*.md, docs/**/*.md

# Config
package.json, pyproject.toml, Cargo.toml

1.2 Audit README Health

Analyze README.md for signs it needs restructuring:

Red Flags (README is bloated):

| Signal | Threshold | Action | |--------|-----------|--------| | Total lines | > 500 lines | Recommend migration | | Commands table | > 20 entries | Move to docs/commands.md | | File structure tree | > 30 lines | Move to docs/file-structure.md | | Configuration section | > 50 lines | Move to docs/configuration.md | | Multiple H2 sections for same topic | Any | Consolidate in docs/ | | Code blocks | > 10 blocks | Move examples to docs/ |

Check for these README sections that belong in docs/:

## Commands Reference      → docs/commands.md
## API Reference           → docs/api.md
## Configuration           → docs/configuration.md
## File Structure          → docs/file-structure.md
## Detailed Examples       → docs/examples.md
## Troubleshooting         → docs/troubleshooting.md
## Architecture            → docs/architecture.md

1.3 Determine Ideal README Structure

A healthy README should have only:

# Project Name

One-line description.

## TL;DR / What is this?
2-3 sentences max.

## Quick Start
5-10 lines of copy-paste commands.

## Documentation
- [Commands Reference](docs/commands.md)
- [Configuration](docs/configuration.md)
- [Contributing](CONTRIBUTING.md)

## License
One line.

---

Phase 2: Detect Changes

For Commit Analysis

git diff --name-only <range>
git diff --stat <range>

For Working Tree Analysis

git status --porcelain
git diff
git diff --cached

Categorize Changes

| Category | Examples | |----------|----------| | Skill/Command | .claude/skills/, .claude/commands/ | | Structure | New directories, renamed files | | Configuration | package.json, settings files | | Feature | New functionality | | Fix | Bug fixes |

---

Phase 3: Route Updates to Correct Location

Routing Table

| Change Type | Target File | NOT README | |-------------|-------------|------------| | New skill/command | docs/commands.md | ~~README commands table~~ | | Skill description changed | docs/commands.md | | | New config option | docs/configuration.md | | | File structure changed | docs/file-structure.md | | | New API endpoint | docs/api.md | | | New workflow pattern | AGENTS.md | | | Quick start broken | README.md | (exception) | | Project description changed | README.md | (exception) | | New major feature | README.md (one line) + docs/ (details) | |

README-Only Updates (Exceptions)

Only update README.md directly for:

1. TL;DR / Description — What the project is
2. Quick Start — Minimal getting-started commands
3. Links section — Adding links to new docs/ files
4. License — License changes
5. Badges — Build status, version badges

Create docs/ Files If Missing

If routing requires a docs/ file that doesn't exist:

1. Create the file with a standard template
2. Add a link to it from README.md
3. Migrate any existing content from README to the new file

Template for new docs/ file:

# {Title}

{Brief description of what this document covers.}

## Overview

{Content migrated from README or new content}

---

*This documentation is auto-maintained. Last updated: {date}*

---

Phase 4: Migrate Bloated README Sections

If Phase 1 audit found README sections that should be in docs/, migrate them.

See MIGRATION.md for:

• Section patterns to look for (Commands, Configuration, API, etc.)
• Step-by-step migration process
• Before/after examples
• Confirmation prompts for large migrations

---

Phase 5: Apply Updates

5.1 Update docs/ Files

For each routed update:

1. Read the target docs/ file
2. Find the relevant section
3. Apply the update (add/modify/remove)
4. Preserve formatting and structure

5.2 Update README Links

If new docs/ files were created, add links to README:

## Documentation

- [Commands Reference](docs/commands.md)
- [Configuration Guide](docs/configuration.md)  ← NEW
- [File Structure](docs/file-structure.md)

5.3 Update AGENTS.md (Conservative)

Only update AGENTS.md when:

• New workflow patterns are introduced
• Integration points change (hooks, verification)
• Operating principles need clarification

Do NOT auto-update:

• Nuanced guidance sections
• Project-specific conventions
• Editorial content

---

Phase 6: Update CHANGELOG

If CHANGELOG.md exists, append entries.

Format Detection

Detect format from existing file:

• Keep a Changelog (most common)
• Conventional Changelog
• Simple list

Entry Generation

## [Unreleased]

### Added
- New `docs/commands.md` for detailed command reference

### Changed
- Migrated commands table from README to docs/

### Fixed
- Fixed broken link in docs/setup.md

Rules:

• Only user-facing changes
• Past tense ("Added", "Fixed")
• One line per entry

---

Phase 7: Create Documentation Commit

Verify Changes

git status --porcelain
git diff --stat

Summary Report

Documentation Updates
=====================

Migrations:
  - README.md → docs/commands.md (142 lines moved)

New files:
  - docs/commands.md (created)

Modified:
  - README.md (replaced section with link)
  - CHANGELOG.md (added entry)

Changes: +156 -142

Create Commit

git add <files>
git commit -m "docs: restructure documentation (README as landing page)

- Migrated commands table to docs/commands.md
- README now links to detailed docs
- Added CHANGELOG entry

Co-Authored-By: Claude <[email protected]>"

---

Edge Cases

No docs/ Directory

• Create docs/ directory
• Create initial files as needed
• Add .gitkeep if empty

README Has No Clear Sections

• Skip migration
• Only add new content to docs/
• Suggest manual restructuring

docs/ File Already Exists with Different Content

• Append new content to existing file
• Don't overwrite existing sections
• Warn if potential conflict

README Is Already Minimal

• Great! Just route new updates to docs/
• No migration needed

Stale Marker File

• Check if marker references old commit
• Ask user how to proceed
• Always clean up marker

---

Configuration (Optional)

Projects can customize via .claude/doc-sync-config.json. See CONFIGURATION.md for full schema.

Key options:

• readme.maxLines: Warn threshold (default: 300)
• routing.*: Customize target docs/ files
• autoMigrate: If true, migrations happen without asking

---

Audit Mode (--audit)

When run with --audit, perform a full health check:

README Health Audit
===================

File: README.md
Lines: 847 (⚠️  > 500 recommended)

Sections that should be in docs/:
  ⚠️  "Commands Reference" (156 lines) → docs/commands.md
  ⚠️  "File Structure" (43 lines) → docs/file-structure.md
  ⚠️  "Configuration" (89 lines) → docs/configuration.md
  ✓  "Quick Start" (12 lines) — OK in README
  ✓  "License" (2 lines) — OK in README

Missing docs/ files:
  ✗  docs/commands.md (would receive 156 lines)
  ✗  docs/configuration.md (would receive 89 lines)

Recommendations:
  1. Run /update-docs --migrate to restructure
  2. README would go from 847 → ~150 lines
  3. Creates 3 new files in docs/

Run migration? [Y/n]

---

Integration with Post-Commit Hook

See POST_COMMIT_HOOK.md for installation.

When triggered by hook:

• Analyze only the most recent commit
• Route updates to correct docs/ files
• Auto-migrate if autoMigrate: true in config
• Create follow-up commit

---

Error Handling

| Situation | Action | |-----------|--------| | README.md does not exist in the project root | Skip README updates; route all changes to docs/ files and suggest creating a README | | git diff returns no changes (nothing to analyze) | Report "No changes detected" and clean up any marker file; do not create an empty docs commit | | Target docs/ file cannot be created (permissions or missing parent directory) | Create docs/ directory if missing; if permissions block creation, report the error and suggest manual resolution | | Marker file (.claude/doc-update-pending.json) references a commit that no longer exists | Warn user that the referenced commit is unreachable, fall back to analyzing HEAD, and clean up the stale marker | | Migration would move content but the destination file already has conflicting sections | Append new content below existing sections rather than overwriting; warn about potential duplication for manual review |

Final Cleanup

Always run at the end:

rm -f .claude/doc-update-pending.json