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: ```bash 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: ```bash 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: ```bash # 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 ```