gh-mgiovani-cc-arsenal/commands/docs/update.md

description, argument-hint, allowed-tools

description	argument-hint	allowed-tools
Update documentation by syncing with current codebase state	[all|<doc-name>|category:<name>]	Read Write Grep Glob Bash(git *)

Update Documentation

Synchronize documentation with the current codebase state. Can update all docs, specific files, or entire categories.

Your Task

1. Parse Arguments:

   • Extract update mode from $ARGUMENTS
   • Modes:
     • No args or all → Update all relevant docs
     • <doc-name> → Update specific doc (e.g., architecture)
     • category:<name> → Update category (e.g., category:data)
   • Default: Update all

2. Determine Update Scope:

   For "all" mode:

   • Analyze entire project
   • Identify all relevant documentation types
   • Update everything that exists or should exist

   For specific doc mode:

   • Validate doc name
   • Find the corresponding file
   • Update only that document

   For category mode:

   • Parse category name: core, data, infrastructure, development
   • Identify all docs in that category
   • Update all docs in the category

3. Analyze Codebase:

   • Detect technology stack
   • Find database models (for data docs)
   • Find deployment configs (for infrastructure docs)
   • Identify services and components (for architecture)
   • Check for recent code changes

4. Check Documentation Freshness:

   # For each doc, compare with related code changes
   !`git log --since="$(git log -1 --format=%ai docs/architecture.md)" --oneline --name-only | head -30`
   

   • Identify which docs are outdated
   • Prioritize updates

5. Load Templates:

   • Template location: commands/docs/templates/
   • Load appropriate templates based on docs being updated

6. Update Each Document:

   • Re-analyze relevant parts of codebase
   • Regenerate diagrams if needed
   • Update content while preserving custom sections
   • Replace placeholders with current values

7. Preserve Custom Content (Important):

   • Keep manually added sections
   • Preserve non-template content
   • Only update auto-generated parts
   • If unsure, ask before overwriting

8. Report Results:

   • List documents updated
   • List documents skipped (up to date)
   • List documents created (if missing)
   • Show summary of changes

Documentation Categories

Core Documentation

Files that are always relevant:

• docs/architecture.md - System architecture
• docs/onboarding.md - Developer onboarding
• docs/adr/ - Architecture Decision Records

Update when: Architecture changes, setup process changes

Data Documentation

Files relevant if database detected:

• docs/data-model.md - Database schema & ER diagrams

Update when: Schema changes, models modified

Infrastructure Documentation

Files relevant if deployment configs detected:

• docs/deployment.md - CI/CD & deployment
• docs/security.md - Security architecture

Update when: Infrastructure changes, security updates

Development Documentation

Files relevant for collaborative projects:

• docs/contributing.md - Contribution guidelines
• docs/rfc/ - RFC documents
• docs/api-documentation.md - API documentation

Update when: Process changes, API changes

Usage

Update all documentation:

/docs:update
/docs:update all

Update specific document:

/docs:update architecture
/docs:update data-model
/docs:update onboarding
/docs:update deployment
/docs:update security

Update entire category:

/docs:update category:core
/docs:update category:data
/docs:update category:infrastructure
/docs:update category:development

With context:

/docs:update architecture after microservices refactor
/docs:update data-model after schema migration
/docs:update category:core for onboarding review

Document Name Mapping

Argument	File Path
architecture	docs/architecture.md
onboarding	docs/onboarding.md
data-model	docs/data-model.md
deployment	docs/deployment.md
security	docs/security.md
contributing	docs/contributing.md
api-docs	docs/api-documentation.md

Update Process Detail

For Architecture Documentation

1. Scan for services, modules, components
2. Identify databases, caches, queues
3. Map data flow
4. Generate architecture diagram
5. Update component descriptions
6. Preserve custom architecture notes

For Data Model Documentation

1. Find ORM models
2. Extract entities and relationships
3. Generate ER diagram
4. Document constraints
5. Update entity descriptions
6. Preserve custom data notes

For Deployment Documentation

1. Find Docker/K8s configs
2. Map services to infrastructure
3. Document CI/CD pipeline
4. Update environment configurations
5. Preserve custom deployment notes

For Security Documentation

1. Find auth/authz code
2. Map security boundaries
3. Document encryption points
4. Identify security controls
5. Preserve custom security notes

Change Detection

# Check what changed since last doc update
!`git log --since="$(git log -1 --format=%ai docs/architecture.md 2>/dev/null || echo '30 days ago')" --oneline`

# Find modified source files
!`git diff --name-only HEAD@{7.days.ago}..HEAD 2>/dev/null | grep -E "\.(py|ts|js|java|go)$" | head -20`

# Check for new files
!`git log --since="7 days ago" --diff-filter=A --name-only --pretty=format: | sort -u | head -20`

Template Placeholder Replacement

Replace these placeholders during update:

• {{PROJECT_NAME}} - Current project name
• {{DATE}} - Current date
• {{TECH_STACK}} - Detected technologies
• {{ER_DIAGRAM}} - Generated ER diagram
• {{ARCHITECTURE_DIAGRAM}} - Generated architecture diagram
• {{ENTITIES}} - Extracted entity descriptions
• {{COMPONENTS}} - Extracted component descriptions

Important Notes

• Preserves custom content: Doesn't blindly overwrite
• Smart updates: Only updates outdated sections
• Diagram regeneration: Auto-regenerates diagrams
• Git-aware: Uses git to detect what changed
• Safe: Asks before major changes
• Incremental: Can be run frequently

Example Output

All Docs Update

Documentation Update Complete ✓

Updated (4 docs):
  ✓ docs/architecture.md (new microservices added)
  ✓ docs/data-model.md (schema changed, ER diagram regenerated)
  ✓ docs/deployment.md (K8s config updated)
  ✓ docs/adr/ (meta-ADR updated)

Up to Date (2 docs):
  • docs/onboarding.md (no changes needed)
  • docs/security.md (no changes needed)

Created (1 doc):
  + docs/contributing.md (collaborative project detected)

Changes Summary:
  - 3 diagrams regenerated
  - 12 sections updated
  - 1 new document created
  - 0 manual sections affected

Specific Doc Update

Architecture Documentation Updated ✓

File: docs/architecture.md

Changes:
  ✓ Added 2 new services (AuthService, NotificationService)
  ✓ Updated architecture diagram
  ✓ Documented new message queue integration
  ✓ Preserved custom deployment notes

Detected:
  - 5 services total
  - 3 databases (PostgreSQL, Redis, MongoDB)
  - 2 message queues (RabbitMQ, Kafka)
  - 8 external API integrations

Diagram: Updated with latest component relationships

Category Update

Core Documentation Category Updated ✓

Updated (3 docs):
  ✓ docs/architecture.md
  ✓ docs/onboarding.md
  ✓ docs/adr/ (5 records)

Changes:
  - Architecture: Added microservices diagram
  - Onboarding: Updated setup instructions for new tooling
  - ADRs: Verified all properly formatted

Next Steps:
  1. Review updated documentation
  2. Consider updating diagrams: /docs:diagram arch
  3. Create new ADR for recent decision: /docs:adr "Decision Title"

When to Run

Run this command:

• After major refactoring
• When database schema changes
• After adding new features or components
• Before onboarding new team members
• When documentation becomes stale
• As part of release process
• After infrastructure changes
• Before documentation reviews

Best Practices

• Run regularly: Keep documentation current
• Review changes: Always review auto-generated updates
• Preserve custom: Keep manual additions safe
• Commit with code: Update docs alongside code changes
• Be specific: Use specific doc names for targeted updates
• Bulk updates: Use category updates for efficiency
• Verify diagrams: Check generated diagrams for accuracy

---

Template Location: commands/docs/templates/ Output Directory: docs/ Safe Mode: Always preserves custom content