/update-docs

Analyzes recent changes in the project and automatically updates all relevant documentation tiers to keep the AI's context synchronized with the code.

This is one of the most important commands for maintaining the effectiveness of the development kit over time.

Core Documentation Principle: Document Current State Only

CRITICAL: This command operates on a strict principle: Always document the current "is" state of the system. The documentation should read as if the current implementation has always existed. It never references legacy implementations or describes what was changed.

  • ❌ Anti-Pattern: "Refactored the API to use streaming instead of batch processing."
  • ✅ Best Practice: "The API uses streaming for real-time data processing."

Auto-Loaded Project Context:

@/CLAUDE.md
@/docs/ai-context/project-structure.md
@/docs/ai-context/docs-overview.md

Command Execution

Step 1: Analyze Changes Based on Input

The command first determines what has changed. You can guide its analysis with arguments:

  • (No input): It analyzes the recent conversation context.
  • Git commit ID: It analyzes a specific commit.
  • uncommitted / staged: It analyzes your local, uncommitted changes.
  • last N commits: It analyzes a range of recent commits.

It then generates a summary of the detected changes, filtering out things that don't require documentation updates (e.g., minor bug fixes, code cleanup).

Step 2-5: Analysis and Strategy

Similar to other commands, /update-docs assesses the complexity of the changes and may use a multi-agent strategy to analyze the impact on documentation across all tiers. It formulates a plan for what documents need to be created or updated.

Step 6-7: Smart File Creation & Updates

Before updating, the AI decides if the changes warrant creating a new CONTEXT.md file (e.g., for a new major component or feature area). If so, it creates the file and adds it to docs-overview.md.

Step 8: Tier-First Documentation Updates

This is the core of the command's operation. It updates documentation in a specific, hierarchical order to ensure consistency.

  1. Tier 3 (Feature-Specific) - START HERE: It begins by updating the most granular CONTEXT.md files closest to the code that changed. These updates include specific implementation details and patterns.

  2. Tier 2 (Component-Level) - CASCADE UP: After Tier 3 is done, it evaluates if the changes have a significant architectural impact on the parent component. If so, it updates the component's CONTEXT.md to reflect the new reality.

  3. Tier 1 (Foundational) - CASCADE UP: Finally, it checks if the changes have system-wide impact. This is where it would update project-structure.md if the file tree or tech stack changed, or other foundational documents for new system-wide patterns.

Step 9: Update Documentation Overview

As a final step, it ensures that docs-overview.md is updated to reflect any new or significantly changed documentation files, keeping the project's documentation map accurate.