update-docs

name	update-docs
description	Documentation Skill: Updates project documentation after shipping to keep README, CLAUDE.md, and docs in sync with code. MANDATORY TRIGGERS: docs, documentation, update docs, document release, sync docs, update readme.
argument-hint

Bobby Docs Skill

Updates project documentation after shipping. Keeps README, CLAUDE.md, and docs in sync with what was actually shipped.

Before Starting

1. Check learnings — Read .claude/skills/bobby-docs/learnings.md + .claude/skills/bobby-docs/learnings.local.md
2. Run bobby ticket list done --sort newest to see recently shipped tickets
3. Run git log --oneline -20 to understand recent changes
4. Read current documentation files in parallel:
   • README.md
   • CLAUDE.md
   • Any docs/ directory if it exists
   • CONTRIBUTING.md if it exists
   • CHANGELOG.md if it exists

Documentation Update Process

Step 1: Identify What Changed

For each recently shipped ticket:

1. Read the ticket's ticket.md and plan.md to understand what was built
2. Check if the changes affect any documented features, APIs, or workflows
3. List which documentation files need updates

Step 2: Update Each File

<update_rules> For each documentation file that needs changes:

README.md:

• Update feature descriptions if new features were shipped
• Update installation/setup instructions if dependencies or config changed
• Update usage examples if CLI or API interfaces changed
• Update screenshots if UI changed significantly
• Do NOT rewrite sections that are still accurate

CLAUDE.md:

• Update agent descriptions if new agents or skills were added
• Update workflow instructions if the workflow changed
• Update CLI command reference if new commands were added
• Keep the "Working Style" and "Safety Rules" sections current

CHANGELOG.md (if it exists):

• Add entries for shipped features, fixes, and improvements
• Follow the existing changelog format (Keep a Changelog, conventional, etc.)
• Group by: Added, Changed, Fixed, Removed

API docs (if they exist):

• Update endpoint documentation for new or changed endpoints
• Update request/response examples
• Update authentication/authorization docs if auth changed </update_rules>

Step 3: Verify Accuracy

<self_check> Before committing documentation changes:

1. Re-read each changed section — does it accurately describe the current code?
2. Are all code examples and commands still correct? Test any CLI commands you documented.
3. Did you update version numbers or dates where applicable?
4. Are there broken links or references to removed features?
5. Is the documentation concise and scannable? Remove filler words and unnecessary explanation. </self_check>

What NOT to Update

- Do not rewrite documentation that is still accurate - Do not add documentation for features that haven't shipped yet - Do not change the documentation style or structure (match existing conventions) - Do not add auto-generated API docs (that's a build tool's job) - Do not update docs for changes in dependencies (unless they affect user-facing behavior)

Completing Work

1. Commit changes: git add changed docs, git commit with docs: update for {brief description of shipped features}
2. If you noticed a documentation pattern: bobby learn bobby-docs "pattern" "description"
3. Output summary listing each file updated and what changed

---

Project overrides

If .claude/skills/bobby-docs/SKILL.local.md exists, read it and follow it. It holds this project's own instructions for this skill and wins wherever it conflicts with anything above.

SKILL.md is shipped by Bobby and is replaced on every upgrade — edits here are lost. SKILL.local.md is yours and is never overwritten.