update-docs

name	update-docs
description	Updates documentation in the repository after completing work. Use when the user explicitly asks to update docs, refresh documentation, or sync docs with code changes.

Update Documentation

Update human-edited markdown documentation files after completing a piece of work.

When to Use

Only when the user explicitly requests documentation updates (e.g., "update the docs", "sync documentation", "refresh the readme").

Process

1. Ask what to review - Before analyzing code, ask the user:

   • Uncommitted changes only (staged + unstaged)
   • Committed changes (all commits on current branch)
   • Both uncommitted and committed changes
   • Whole repo (review entire codebase, not just recent changes)

   For uncommitted/committed/both:

   • Use git diff for uncommitted changes
   • For committed changes, review all commits unique to the current branch (use git log main..HEAD or similar)
   • Focus documentation updates on what changed

   For "Whole repo" option:

   • Explore the codebase structure (key directories, main files, entry points)
   • Identify features, APIs, and components
   • Compare existing documentation against actual code
   • Look for undocumented features, outdated information, or missing sections
   • This is useful for documentation audits or when docs have drifted significantly from code

2. Identify documentation files - Search for:

   • README.md files (root and nested)
   • docs/ or documentation/ folders
   • agents.md, claude.md, or similar project-specific docs
   • Any other .md files that appear to be human-edited

3. Filter out auto-generated and special files - Skip:

   • Auto-generated documentation (look for generation comments/headers)
   • LICENSE, LICENSE.md
   • CONTRIBUTING.md
   • CHANGELOG.md, HISTORY.md
   • CODE_OF_CONDUCT.md
   • Files with "auto-generated" or "do not edit" markers

   If the user wants these files updated, ask for explicit confirmation first.

4. Review existing conventions - Before making changes:

   • Read the existing documentation style and formatting
   • Match the tone (formal vs casual)
   • Follow existing heading structures
   • Preserve any existing patterns for code examples, links, etc.

5. If no documentation exists - Work with the user to initialize:

   • Ask what documentation they want to create
   • Suggest a basic structure based on the project type
   • Start minimal and expand based on feedback

6. Make targeted updates:

   • For change-based reviews: only update sections relevant to the changes
   • For whole repo reviews: address gaps, outdated info, and missing documentation
   • Don't rewrite entire documents unnecessarily
   • Add new sections for undocumented features
   • Update existing sections if behavior differs from docs
   • Remove outdated information

What to Document

Based on the work completed, consider updating:

• Features/Usage: New functionality, how to use it, examples
• Installation/Setup: New dependencies, configuration options
• API Reference: New endpoints, functions, parameters
• Architecture: Structural changes, new components
• Examples: Working code snippets demonstrating changes

Guidelines

• Keep documentation concise and scannable
• Use code blocks with appropriate language tags
• Prefer examples over lengthy explanations
• Link to related documentation rather than duplicating
• Maintain consistent formatting with existing docs