Initial commit
This commit is contained in:
Zhongwei Li
308
commands/docs/update.md
Normal file
308
commands/docs/update.md
Normal file
@@ -0,0 +1,308 @@
|
||||
---
|
||||
description: "Update documentation by syncing with current codebase state"
|
||||
argument-hint: "[all|<doc-name>|category:<name>]"
|
||||
allowed-tools: ["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**:
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
Reference in New Issue
Block a user