update-docs

/update-docs

Find and fix stale documentation after API changes.

EXECUTE THESE STEPS NOW

When this skill is invoked, you MUST execute these steps immediately.

Step 1: Identify Changed Files

Run:

git diff --name-only main...HEAD -- '*.py'

If no changes are found relative to main (e.g., on main or no upstream), fall back to:

git diff --name-only HEAD~1 -- '*.py'

If that also fails, ask the user which files changed.

Collect the list of changed Python files.

Step 2: Extract API Changes

For each changed .py file, compare old vs new signatures using the same ref that worked in Step 1:

# If Step 1 used main...HEAD:
git diff main...HEAD -- <file>

# If Step 1 fell back to HEAD~1:
git diff HEAD~1 -- <file>

Look for changes to:

• Function/method signatures (def lines)
• Class names and init signatures
• Module-level constants and type aliases
• Removed or renamed public symbols

Build a list of (old_signature, new_signature) pairs.

If no API changes are found (only internal logic changes), report "No API changes detected — no docs update needed" and stop.

Step 3: Spawn Docs Updater Agent

Use the Task tool to spawn the docs-updater agent. IMPORTANT: the description field MUST contain "docs-updater" so the SubagentStop hook fires correctly.

Task tool:
  subagent_type: general-purpose
  description: "docs-updater propagation"
  prompt: |
    You are a docs-updater agent. Read .claude/agents/docs-updater.md
    for your full instructions.

    Here are the API changes to propagate:

    Changed files: <list>
    API changes:
    - `old` → `new`
    ...

    Search the entire repo for references to the old APIs and update
    them to match the new signatures. Follow the process in
    .claude/agents/docs-updater.md exactly.

Step 4: Review Results

After the agent returns:

• Review the update report
• Verify no test files were touched
• Verify changes are minimal and correct

Report the summary to the user.

When to Use

• After /implement when API signatures changed
• Before /pre-submit-pr to ensure docs are fresh
• When refactoring public APIs

When NOT to Use

• Internal-only changes (no public API affected)
• Test-only changes
• Documentation-only changes (no code changed)

Workflow Integration

/write-tests    →  Red (failing tests)
/implement      →  Green (passing tests)
/update-docs    →  Fix stale docs across repo  ← THIS SKILL
/simplify       →  Refactor (optional)
/pre-submit-pr  →  Validate before PR