steveclarke Update Docs
Run this after any meaningful change to the codebase. It checks every documentation location, determines what's stale, and updates it.
Step 1 — Understand what changed
# Changes on the current branch vs master
git log --oneline master..HEAD
git diff --stat master..HEAD
# Or if working on master, recent commits
git log --oneline -10
Summarize the changes in one sentence. Classify:
| Type | Example |
|---|---|
| New command | Added outport open |
| Command change | New flag, changed output format |
| Config change | New field in outport.yml |
| Infrastructure | Build, CI, dependency changes |
| Bug fix | Fixed registry save race condition |
Step 2 — Check each documentation location
Go through every location below. For each one, check whether it's current.
README.md
| Check | What to look for |
|---|---|
| Commands list | Does it match actual commands in cmd/*.go? |
| Config example | Does outport.yml example match current schema? |
| "How It Works" section | Does it reflect current allocation behavior? |
| Install instructions | Are they still accurate? |
CLAUDE.md
| Check | What to look for |
|---|---|
| Architecture section | Do package descriptions match current code? |
| CLI commands list | Does it include all commands in cmd/*.go? |
| Key design decisions | Do they reflect current behavior? |
| Development commands | Does the justfile have new/changed recipes? |
cmd/init.go presets
| Check | What to look for |
|---|---|
| Service presets | Does the presets slice include all standard services? |
| Preset fields | Do presets use the current config field names? |
.goreleaser.yml
| Check | What to look for |
|---|---|
| Build targets | Do platforms match what's documented? |
| Homebrew formula | Is the tap config current? |
docs/ (VitePress site)
| Check | What to look for |
|---|---|
docs/reference/commands.md |
Does it list all commands in cmd/*.go? |
docs/reference/configuration.md |
Does it cover all outport.yml fields? |
docs/guide/getting-started.md |
Does it reflect current workflow? |
docs/guide/examples.md |
Are examples using current config syntax? |
docs/guide/tips.md |
Are troubleshooting tips still accurate? |
skills/outport/SKILL.md (user-facing skill, NOT .claude/skills/)
This is the Outport skill that users download and install in their own projects. It lives at skills/outport/SKILL.md in the repo root — not in .claude/skills/ which is for Claude Code's internal skills.
| Check | What to look for |
|---|---|
| Quick Reference commands | Does it list all commands? |
| Common Tasks section | Does it cover current capabilities? |
| Trigger keywords | Do they cover all features? |
Step 3 — Report findings
Present as a table, only showing items that need attention:
| Status | File | What needs updating |
|--------|------|---------------------|
| STALE | README.md | Commands list missing `open` |
| OK | CLAUDE.md | — |
Step 4 — Make the updates
For each STALE item, update the file. Rules:
- Don't duplicate content. README is the user-facing overview. CLAUDE.md is the agent-facing architecture guide. Don't copy between them.
- README should describe what commands do, not how they're implemented.
- CLAUDE.md should describe architecture and conventions, not user-facing docs.
Quick reference — what to update per change type
| Change type | Always update | Check if needed |
|---|---|---|
| New command | README commands, CLAUDE.md commands, docs/reference/commands.md, skills/outport/SKILL.md | init presets, docs/guide/getting-started.md, docs/guide/tips.md |
| Config schema change | README config example, CLAUDE.md config description, docs/reference/configuration.md | init presets, docs/guide/examples.md |
| New convention | CLAUDE.md | — |
| Infrastructure | — | CLAUDE.md dev commands |
| Bug fix | — | README (if workaround documented), docs/guide/tips.md |