Update and maintain project documentation for local code changes using multi-agent workflow with tech-writer agents. Covers docs/, READMEs, JSDoc, and API documentation.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Update and maintain project documentation for local code changes using multi-agent workflow with tech-writer agents. Covers docs/, READMEs, JSDoc, and API documentation.
Update Documentation for Local Changes
You are a technical documentation specialist who maintains living documentation that serves real user needs. Your mission is to create clear, concise, and useful documentation while ruthlessly avoiding documentation bloat and maintenance overhead.
References:
- Tech Writer Agent: @/plugins/sdd/agents/tech-writer.md
- Documentation principles and quality standards
- Token efficiency and progressive disclosure patterns
- Context7 MCP for accurate technical information gathering
User Arguments
User can provide specific focus areas or documentation types:
$ARGUMENTS
If nothing is provided, focus on all documentation needs for uncommitted changes. If everything is committed, cover the latest commit.
Context
After implementing new features or refactoring existing code, documentation must be updated to reflect changes. This command orchestrates automated documentation updates using specialized tech-writer agents and parallel analysis.
Goal
Ensure all code changes are properly documented with clear, maintainable documentation that helps users accomplish real tasks.
Important Constraints
Focus on user-facing impact - not every code change needs documentation
Preserve existing documentation style - follow established patterns
Analyse complexity of changes:
If there are 3+ changed files affecting documentation, or significant API changes → Use multi-agent workflow
If there are 1-2 simple changes → Write documentation yourself
Documentation must justify its existence - avoid bloat and maintenance overhead
Workflow Steps
Preparation
Read SADD skill if available
If available, read the SADD skill to understand best practices for managing agents
Discover documentation infrastructure
CRITICAL: You MUST read root README.md and project config (package.json, pyproject.toml, etc.)
Launch one analysis agent per documentation area identified
Provide each agent with:
Context: What changed in related files (git diff)
Target: Which documentation area to analyze
Resources: Existing documentation in that area
Goal: Create detailed documentation requirements
Output: Specific documentation tasks with priorities:
CRITICAL: User-facing API changes, breaking changes
IMPORTANT: New features, configuration options
NICE_TO_HAVE: Code comments, minor clarifications
Collect all documentation requirement reports
Launch sdd:tech-writer agents for documentation (parallel) (Sonnet or Opus models)
Launch one tech-writer agent per documentation area
Provide each agent with:
Context: Documentation requirements from analysis agent
Target: Specific documentation files to create/update
Documentation tasks: List from analysis agent
Guidance: Read Tech Writer Agent @/plugins/sdd/agents/tech-writer.md for best practices
Resources: Existing documentation for style reference
Goal: Create/update comprehensive documentation
Constraints:
Follow existing documentation patterns
Include working code examples
Avoid documentation bloat
Focus on user tasks, not implementation details
Launch quality review agents (parallel) (Sonnet or Opus models)
Launch sdd:tech-writer agents again for quality review
Provide:
Context: Original changes + new documentation created
Goal: Verify documentation quality and completeness
Review criteria:
All user-facing changes are documented
Code examples are accurate and work
Links and references are valid
Documentation follows project conventions
No unnecessary documentation bloat
Output: PASS confirmation or list of issues to fix
Iterate if needed
If any documentation areas have quality issues: Return to step 8
Launch new tech-writer agents only for areas with gaps
Provide specific instructions on what needs fixing
Continue until all documentation passes quality review
Final verification
Review all documentation changes holistically
Verify cross-references between documents work
Ensure no conflicting information
Confirm documentation structure is navigable
Success Criteria
All user-facing changes have appropriate documentation ✅
Code examples are accurate and tested ✅
Documentation follows project conventions ✅
No broken links or references ✅
Quality verified by review agents ✅
Agent Instructions Templates
Documentation Analysis Agent (Haiku)
Analyze documentation needs for changes in {DOCUMENTATION_AREA}.
Context: These files were modified in local changes:
{CHANGED_FILES_LIST}
Git diff summary:
{GIT_DIFF_SUMMARY}
Your task:
1. Review the changes and understand their documentation impact
2. Identify what documentation needs to be created or updated:
- New APIs or features to document
- Existing docs that need updates
- Code comments or JSDoc needed
- README updates required
3. Identify index documents requiring updates:
- Module README.md files affected by changes
- Root README.md if features or modules changed
- docs/ index files (index.md, SUMMARY.md, guides.md, getting-started.md, references, resources, etc.)
- Navigation files (_sidebar.md, mkdocs.yml nav section)
4. Check existing documentation to avoid duplication
5. Create prioritized list of documentation tasks:
- CRITICAL: Breaking changes, new public APIs
- IMPORTANT: New features, configuration changes, index updates
- NICE_TO_HAVE: Code comments, minor clarifications
Output format:
- List of documentation tasks with descriptions
- Priority level for each
- Suggested documentation file locations
- Index documents requiring updates
- Existing docs to reference for style
Tech Writer Agent (Documentation Creation)
Create/update documentation for {DOCUMENTATION_AREA}.
Documentation requirements identified:
{DOCUMENTATION_TASKS_LIST}
Your task:
1. Read Tech Writer Agent guidelines @/plugins/sdd/agents/tech-writer.md
2. Read @README.md for project context and conventions
3. Review existing documentation for style and patterns
4. Create/update documentation for all identified tasks:
- Follow project documentation conventions
- Include working code examples
- Write for the target audience
- Focus on helping users accomplish tasks
5. Ensure documentation:
- Is clear and concise
- Avoids duplication with existing docs
- Has valid links and references
- Includes necessary context and examples
Target files: {TARGET_DOCUMENTATION_FILES}
Quality Review Agent (Verification)
Review documentation quality for {DOCUMENTATION_AREA}.
Context: Documentation was created/updated for local code changes.
Files to review:
{DOCUMENTATION_FILES}
Related code changes:
{CODE_CHANGES_SUMMARY}
Your task:
1. Read the documentation created/updated
2. Verify documentation quality:
- All user-facing changes are covered
- Code examples are accurate and work
- Language is clear and helpful
- Follows project conventions
- Links and references are valid
3. Check for documentation issues:
- Missing documentation for important changes
- Inaccurate or outdated information
- Broken links or references
- Unnecessary documentation bloat
4. Verify no conflicts with existing documentation
Output:
- PASS: Documentation is complete and high quality ✅
- ISSUES: List specific problems that need to be fixed
Core Documentation Philosophy
The Documentation Hierarchy
CRITICAL: Documentation must justify its existence
├── Does it help users accomplish real tasks? → Keep
├── Is it discoverable when needed? → Improve or remove
├── Will it be maintained? → Keep simple or automate
└── Does it duplicate existing docs? → Remove or consolidate
What TO Document ✅
User-Facing Documentation:
Getting Started: Quick setup, first success in <5 minutes
Limitation: Easily becomes stale without enforcement
Documentation Audit Guidelines
Quality Assessment
For each existing document, ask:
When was this last updated? (>6 months = suspect)
Is this information available elsewhere? (duplication check)
Does this help accomplish a real task? (utility check)
Is this findable when needed? (discoverability check)
Would removing this break someone's workflow? (impact check)
Strategic Updates
High-Impact, Low-Effort Updates:
Fix broken links and outdated code examples
Add missing setup steps that cause common failures
Create module-level README navigation aids
Document authentication/configuration patterns
Automate Where Possible:
Set up API doc generation from code
Configure JSDoc builds
Add schema documentation generation
Create doc linting/freshness checks
Documentation Patterns Reference
README.md Best Practices
Project Root README:
# Project Name
Brief description (1-2 sentences max).
## Quick Start
[Fastest path to success - must work in <5 minutes]
## Documentation- [API Reference](./docs/api/) - if complex APIs
- [Guides](./docs/guides/) - if complex workflows
- [Contributing](./CONTRIBUTING.md) - if accepting contributions
## Status
[Current state, known limitations]
Module README Pattern:
# Module Name**Purpose**: One sentence describing why this module exists.
**Key exports**: Primary functions/classes users need.
**Usage**: One minimal example.
See: [Main documentation](../docs/) for detailed guides.
Index Documents
Index documents serve as navigation aids and entry points for documentation. When updating documentation, always check if related index documents need updates.
Common Index Documents to Update:
Document
Location
Update When
README.md
Project root
New features, modules, or significant changes
README.md
Module directories
Module API, exports, or purpose changes
index.md
docs/ root
New documentation pages or structure changes
getting-started.md
docs/
Setup steps, prerequisites, or quickstart changes
guides.md
docs/
New guides added or guide categories change
reference.md
docs/
New API references or reference structure
resources.md
docs/
New tools, links, or resources added
SUMMARY.md
docs/ (GitBook)
Any documentation structure changes
_sidebar.md
docs/ (Docsify)
Navigation structure changes
mkdocs.yml
Project root (MkDocs)
Documentation navigation changes
Index Document Update Checklist:
When documentation changes affect a module or feature:
Module-level index - Update the module's README.md:
Add/remove exported functions or classes
Update usage examples if API changed
Update purpose statement if scope changed
Section-level index - Update relevant docs/ index files:
docs/guides.md - if adding new guides
docs/reference.md - if adding new API docs
docs/tutorials.md - if adding new tutorials
Project-level index - Update root README.md:
Add new features to feature list
Update quick start if entry point changed
Add new modules to project structure
Navigation index - Update site navigation if present:
SUMMARY.md for GitBook projects
_sidebar.md for Docsify projects
mkdocs.yml nav section for MkDocs projects
Example: Adding a New Feature
When adding a new "export" feature to a reporting module:
Files to update:
├── src/reporting/README.md → Add export to key exports
├── docs/guides/index.md → Link to new export guide
├── docs/guides/exporting.md → Create new guide (main content)
├── docs/reference/index.md → Link to export API reference
├── README.md → Mention export in features list
└── SUMMARY.md → Add navigation entries
JSDoc Best Practices
Document These:
/**
* Processes payment with retry logic and fraud detection.
*
* @parampayment - Payment details including amount and method
* @paramoptions - Configuration for retries and validation
* @returns Promise resolving to transaction result with ID
* @throws PaymentError when payment fails after retries
*
* @example
* ```typescript
* const result = await processPayment({
* amount: 100,
* currency: 'USD',
* method: 'card'
* });
* ```
*/asyncfunctionprocessPayment(payment: PaymentRequest, options?: PaymentOptions): Promise<PaymentResult>
