Documentation Sync Command
You are performing a documentation synchronization. Your goal is to analyze the current state of the codebase and update the documentation in ${SMART_DOCS_PATH} to accurately reflect it.
Phase 1: Codebase Analysis
First, thoroughly analyze the codebase to understand its current state:
-
Project Structure
- Identify the main source directories
- Find entry points (main files, index files, CLI entry)
- Map the module/component structure
-
Public API Surface
- Find exported functions, classes, and types
- Identify REST/GraphQL endpoints if applicable
- Note CLI commands and options
- Document configuration options
-
Key Patterns
- Identify architectural patterns in use
- Note naming conventions
- Find error handling patterns
- Identify testing patterns
-
Dependencies
- Check package.json or equivalent for key dependencies
- Note any peer dependencies or required tools
Phase 2: Documentation Audit
Read the existing documentation in ${SMART_DOCS_PATH}:
-
Inventory existing docs
- List all markdown files
- Note their topics and coverage
- Check frontmatter for completeness
-
Identify gaps
- Features in code but not documented
- API endpoints missing documentation
- Configuration options not explained
-
Identify stale content
- Documented features that no longer exist
- Outdated API signatures or examples
- Deprecated patterns still referenced
- Version numbers or dependencies out of date
-
Check accuracy
- Verify code examples still work
- Confirm file paths mentioned exist
- Validate command-line examples
Phase 3: Plan Updates
Before making changes, create a todo list with:
- New documentation needed - Files to create
- Updates required - Existing files that need modification
- Removals - Content to delete (deprecated features)
- Reorganization - Structure changes if needed
Present this plan to the user and ask for confirmation before proceeding.
Phase 4: Apply Updates
For each documentation update:
- Preserve frontmatter - Keep existing
autoLoad, autoLoadPriority, and other custom fields
- Maintain style - Match the existing documentation tone and format
- Update incrementally - Use Edit tool for targeted changes rather than full rewrites
- Add examples - Include working code examples where helpful
- Cross-reference - Update links between documents if structure changes
Frontmatter Template
Ensure all docs have proper frontmatter:
---
title: Clear, Descriptive Title
description: One-line summary for previews and search
---
For critical reference docs, suggest adding:
autoLoad: true
autoLoadPriority: 5
agentRole: reference
Phase 5: Verification
After updates:
- List all changes made
- Verify no broken internal links
- Confirm code examples are syntactically valid
- Summarize what was added/updated/removed
Important Guidelines
- Ask before major changes - If you discover the docs need significant restructuring, ask the user first
- Preserve custom content - Don't remove user-written explanations or context
- Be conservative - When unsure if something is outdated, ask rather than delete
- Note uncertainty - If you can't verify something, flag it for user review
- Keep it concise - Update docs to be accurate, don't pad with unnecessary content
Output Format
When complete, provide a summary:
## Documentation Sync Complete
### Added
- path/to/new-doc.md - Description
### Updated
- path/to/updated.md - What changed
### Removed
- path/to/old-doc.md - Why removed
### Flagged for Review
- path/to/uncertain.md - What needs human verification