/docs

Comprehensively analyze your codebase and update all documentation files to ensure they accurately reflect the current state of your project. Uses the docs-manager agent to maintain synchronized, high-quality documentation.

Syntax

/docs:update [additional requests]

Parameters

  • [additional requests] (optional): Specific documentation updates or focus areas

How It Works

The /docs:update command uses the docs-manager agent with this workflow:

1. Codebase Analysis

  • Generates comprehensive codebase compaction using repomix
  • Creates/updates ./docs/codebase-summary.md
  • Scans project structure and architecture
  • Identifies key components and patterns
  • Analyzes dependencies and integrations

2. Documentation Review

  • Reads all existing documentation in ./docs/ directory
  • Identifies outdated information
  • Finds gaps and inconsistencies
  • Cross-references with actual code implementation
  • Checks examples and code snippets for accuracy

3. Systematic Updates

  • Updates each documentation file:
    • README.md - Project overview and quick start
    • docs/project-overview-pdr.md - Product Development Requirements
    • docs/codebase-summary.md - Comprehensive codebase summary
    • docs/code-standards.md - Codebase structure and standards
    • docs/system-architecture.md - System architecture documentation
    • docs/project-roadmap.md - Project roadmap and future plans
    • docs/deployment-guide.md (optional) - Deployment instructions
    • docs/design-guidelines.md (optional) - Design system guidelines

4. Quality Assurance

  • Ensures consistent formatting and terminology
  • Validates all links and references
  • Verifies code examples are functional
  • Maintains documentation hierarchy
  • Updates version information and timestamps

When to Use

✅ Perfect For

After Major Features

# Implemented new authentication system
/docs:update

Refactoring Projects

# Refactored entire API layer
/docs:update [focus on API architecture changes]

New Team Members

# Preparing documentation for onboarding
/docs:update [ensure all setup instructions are current]

Pre-Release

# Before version release
/docs:update [prepare for v2.0 release]

Quarterly Maintenance

# Regular documentation review
/docs:update [quarterly documentation audit]

❌ Don’t Use For

Simple Typos

❌ /docs:update [fix typo in README]
✅ Just edit the README directly

No Code Changes

❌ /docs:update [just checking]
✅ Only run after meaningful code changes

Quick Status Check

❌ /docs:update [what changed?]
✅ /watzup [review recent changes]

Examples

After Feature Implementation

/docs:update

What happens:

1. Analyzing codebase
   $ repomix
   ✓ Generated: ./repomix-output.xml (245KB, 45K tokens)
   ✓ Created: ./docs/codebase-summary.md

2. Reviewing existing documentation
   - README.md: Outdated (mentions old API structure)
   - project-overview-pdr.md: Missing new features
   - code-standards.md: Current
   - system-architecture.md: Needs update (new microservices)
   - codebase-summary.md: Regenerated

3. Updating documentation
   ✓ README.md
     - Updated API endpoint examples
     - Added new environment variables
     - Refreshed feature list

   ✓ project-overview-pdr.md
     - Added OAuth2 authentication section
     - Updated technical requirements
     - Added new acceptance criteria

   ✓ system-architecture.md
     - Added payment service architecture
     - Updated database schema diagram
     - Documented new message queue integration

   ✓ codebase-summary.md
     - Complete project structure overview
     - File organization and naming conventions
     - Key architectural patterns

4. Summary
   Files updated: 4
   Sections added: 12
   Examples refreshed: 8
   Broken links fixed: 3

✓ Documentation synchronized (3m 45s)

Focused Update

/docs:update [update API documentation with new endpoints]

What happens:

1. Analyzing API changes
   - New endpoints: 5 (user management)
   - Modified endpoints: 3 (authentication)
   - Deprecated endpoints: 1 (legacy login)

2. Updating API documentation
   ✓ project-overview-pdr.md
     - Added API endpoints section
     - Documented request/response formats
     - Added authentication requirements

   ✓ code-standards.md
     - Updated API design patterns
     - Added endpoint naming conventions
     - Documented error response structure

   ✓ README.md
     - Added API quick start examples
     - Updated authentication flow

3. Validation
   - All endpoints documented
   - Request examples tested
   - Response schemas validated

✓ API documentation updated (2m 12s)

Pre-Release Documentation

/docs:update [prepare documentation for v2.0 release]

What happens:

1. Comprehensive review
   - Reviewing 8 documentation files
   - Checking 156 code examples
   - Validating 43 links

2. Major updates
   ✓ README.md
     - Updated version to 2.0
     - Added breaking changes section
     - Refreshed installation instructions

   ✓ project-overview-pdr.md
     - Added v2.0 features overview
     - Updated technical requirements
     - Added migration guide from v1.x

   ✓ project-roadmap.md
     - Marked v2.0 items as completed
     - Added v2.1 and v3.0 planning
     - Updated timeline

   ✓ deployment-guide.md
     - Updated for new deployment architecture
     - Added Docker Compose examples
     - Documented environment variables

3. Quality checks
   ✓ All links validated
   ✓ Code examples tested
   ✓ Consistent formatting applied
   ✓ Version numbers updated throughout

✓ Release documentation ready (4m 23s)

Architecture Documentation

/docs:update [focus on system architecture]

What happens:

1. Architecture analysis
   - Microservices: 7 services identified
   - Databases: 2 (PostgreSQL, Redis)
   - Message queues: RabbitMQ
   - External APIs: 4 integrations

2. Updating system-architecture.md
   ✓ Added system overview diagram
   ✓ Documented each microservice
     - API Gateway
     - Auth Service
     - User Service
     - Payment Service
     - Notification Service
     - Analytics Service
     - Background Job Service

   ✓ Database architecture
     - Schema relationships
     - Migration strategy
     - Backup procedures

   ✓ Communication patterns
     - REST APIs
     - Message queue flows
     - WebSocket connections

   ✓ Deployment architecture
     - Container orchestration
     - Load balancing
     - Scaling strategies

✓ Architecture documentation complete (3m 56s)

Documentation Files Updated

Core Documentation

README.md

  • Project overview
  • Quick start guide
  • Installation instructions
  • Basic usage examples
  • Contributing guidelines

docs/project-overview-pdr.md

  • Product vision and goals
  • Functional requirements
  • Non-functional requirements
  • Technical constraints
  • Acceptance criteria
  • Success metrics

docs/codebase-summary.md

  • Project structure overview
  • File organization
  • Key components
  • Architectural patterns
  • Token count and statistics

docs/code-standards.md

  • Coding conventions
  • File naming patterns
  • Directory structure
  • Error handling patterns
  • Testing strategies
  • Security practices

docs/system-architecture.md

  • High-level architecture
  • Component diagrams
  • Data flow
  • Technology stack
  • Integration points
  • Deployment architecture

Optional Documentation

docs/project-roadmap.md

  • Feature timeline
  • Release planning
  • Future improvements
  • Technical debt tracking

docs/deployment-guide.md

  • Deployment procedures
  • Environment setup
  • Configuration management
  • Monitoring and logging

docs/design-guidelines.md

  • UI/UX patterns
  • Component library
  • Design system
  • Accessibility guidelines

Agent Invoked

The command uses the docs-manager agent with these capabilities:

  • Documentation Analysis: Systematic review of all documentation
  • Codebase Synchronization: Cross-referencing docs with code
  • Standards Enforcement: Consistent formatting and terminology
  • Gap Identification: Finding missing or outdated documentation
  • Quality Assurance: Validating examples, links, and references

Best Practices

Run After Major Changes

✅ Good - After meaningful work:

# After implementing features
/cook [add payment integration]
/fix:types
/test
/docs:update

# Commit everything together
/git:cm

❌ Bad - Too frequent:

# After every tiny change
/fix:fast [typo]
/docs:update  # Wasteful

Provide Context

✅ Specific focus:

/docs:update [focus on API changes and authentication flow]

❌ No context:

/docs:update  # Works but less targeted

Review Before Committing

✅ Review changes:

/docs:update
git diff docs/
# Review changes
/git:cm

Workflow

Standard Feature Development

# 1. Plan feature
/plan [add OAuth2 authentication]

# 2. Implement feature
/cook [implement OAuth2 with Google and GitHub providers]

# 3. Fix any issues
/fix:types
/test

# 4. Update documentation
/docs:update [document OAuth2 implementation]

# 5. Review and commit
git diff
/git:cm

Quarterly Documentation Maintenance

# 1. Update documentation
/docs:update [quarterly documentation review]

# 2. Review all changes
git diff docs/

# 3. Commit documentation updates
/git:cm

Pre-Release Checklist

# 1. Update documentation
/docs:update [prepare for v2.0 release]

# 2. Review roadmap
# Edit docs/project-roadmap.md

# 3. Update changelog
# Edit CHANGELOG.md

# 4. Commit release documentation
/git:cm

# 5. Create release PR
/git:pr main develop

Troubleshooting

Incomplete Updates

Problem: Some documentation files not updated

Solution:

# Specify which files need attention
/docs:update [update system-architecture.md and deployment-guide.md]

Outdated Examples

Problem: Code examples in docs don’t match current code

Solution:

# Command automatically detects and updates
/docs:update

# Or specify focus
/docs:update [refresh all code examples]

Missing Documentation

Problem: New features not documented

Solution:

# Command will create missing sections
/docs:update [document new payment service]

Formatting Issues

Problem: Inconsistent formatting across docs

Solution:

# Command standardizes formatting
/docs:update

Documentation Overview

# Quick summary of recent changes
/watzup

# Full documentation update
/docs:update

Codebase Summary Only

# Just update codebase summary
/docs:summarize

# Full documentation update
/docs:update

Initialize Documentation

# First-time documentation setup
/docs:init

# Regular updates thereafter
/docs:update

Output Structure

After running /docs:update, your documentation structure:

./
├── README.md (updated)
├── docs/
│   ├── project-overview-pdr.md (updated)
│   ├── codebase-summary.md (regenerated)
│   ├── code-standards.md (updated)
│   ├── system-architecture.md (updated)
│   ├── project-roadmap.md (updated)
│   ├── deployment-guide.md (optional, updated)
│   └── design-guidelines.md (optional, updated)
└── repomix-output.xml (generated)

Metrics

Typical /docs:update performance:

  • Time: 3-5 minutes (depending on codebase size)
  • Files analyzed: Entire codebase
  • Files updated: 4-8 documentation files
  • Code examples validated: All examples in documentation
  • Links checked: All internal and external links

Next Steps

After using /docs:update:

  • /docs
     - Update just codebase summary
  • /watzup - Review recent changes
  • /git
     - Commit documentation updates

Key Takeaway: /docs:update ensures your documentation stays synchronized with your codebase through comprehensive analysis and systematic updates across all documentation files.