# Documentation Subagent Guide This guide covers documentation-focused subagents: - **documenter**: User docs, API specs, feature documentation - **describer-for-ai**: Technical docs for AI, ADRs, system overviews - **planner**: Feature breakdown, roadmaps, scope management - **product-owner**: Requirements, user stories, backlog prioritization ## The documenter Subagent ### When to Use Use the **documenter** subagent when you need to: - Write user-facing documentation - Create API endpoint documentation - Document feature usage guides - Write setup or installation guides - Create troubleshooting guides ### What documenter Knows The documenter subagent understands: - Markdown formatting and best practices - API documentation standards - User documentation patterns - Project-specific terminology - Existing documentation structure ### Example Requests **API Documentation:** ``` "Use documenter to create API documentation for the shopping list endpoints. Include request/response schemas, authentication requirements, and example curl commands." ``` **Feature Guide:** ``` "Use documenter to write a user guide for the price watchlist feature. Explain how to add items, set price alerts, and view price history." ``` **Troubleshooting Guide:** ``` "Use documenter to create a troubleshooting guide for common flyer upload issues, including file format errors, size limits, and processing failures." ``` ### Documentation Standards #### API Documentation Format ````markdown ### [METHOD] /api/endpoint **Description**: Brief purpose of the endpoint **Authentication**: Required (Bearer token) **Request**: - Headers: `Content-Type: application/json`, `Authorization: Bearer {token}` - Body: ```json { "field": "string (required) - Description", "optional_field": "number (optional) - Description" } ``` ```` **Response**: - Success (200): ```json { "success": true, "data": { ... } } ``` - Error (400): ```json { "success": false, "error": { "code": "VALIDATION_ERROR", "message": "Description of error" } } ``` **Example**: ```bash curl -X POST https://api.example.com/api/endpoint \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d '{"field": "value"}' ``` ```` ## The describer-for-ai Subagent ### When to Use Use the **describer-for-ai** subagent when you need to: - Write Architecture Decision Records (ADRs) - Create technical specifications for AI consumption - Document system architecture for context - Write CLAUDE.md updates - Create technical overviews ### What describer-for-ai Knows The describer-for-ai subagent understands: - ADR format and conventions - Technical documentation for AI assistants - System architecture patterns - Project conventions and patterns - How to provide context efficiently for AI ### ADR Format ```markdown # ADR-NNN: Title of Decision **Date**: YYYY-MM-DD **Status**: Proposed | Accepted | Implemented | Superseded ## Context Describe the problem space and constraints that led to this decision. ## Decision The chosen solution and its rationale. ## Consequences ### Positive - Benefits of this decision ### Negative - Trade-offs or limitations ### Neutral - Other notable effects ## Implementation Details Technical details, code examples, configuration. ## Key Files - `path/to/file.ts` - Description - `path/to/other.ts` - Description ## Related ADRs - [ADR-XXX](./XXXX-title.md) - Related decision ```` ### Example Requests **Creating an ADR:** ``` "Use describer-for-ai to create an ADR for adding websocket support for real-time price alerts. Include the technical approach, alternatives considered, and implementation details." ``` **CLAUDE.md Update:** ``` "Use describer-for-ai to update CLAUDE.md with the new authentication flow and any new patterns developers should be aware of." ``` **Technical Overview:** ``` "Use describer-for-ai to create a technical overview of the caching layer for future AI context, including how Redis is used, cache invalidation patterns, and key prefixes." ``` ## The planner Subagent ### When to Use Use the **planner** subagent when you need to: - Break down a feature into tasks - Create implementation roadmaps - Scope work for sprints - Identify dependencies - Estimate effort ### What planner Knows The planner subagent understands: - Project architecture and conventions - Existing codebase structure - Common implementation patterns - Task estimation heuristics - Dependency identification ### Example Requests **Feature Breakdown:** ``` "Use planner to break down the 'store comparison' feature into implementable tasks. Include frontend, backend, and database work. Identify dependencies between tasks." ``` **Roadmap Planning:** ``` "Use planner to create a roadmap for the Q2 features: recipe integration, mobile app preparation, and store notifications. Identify what can be parallelized." ``` **Scope Assessment:** ``` "Use planner to assess the scope of adding multi-language support. What systems would need to change? What's the minimum viable implementation?" ``` ### Planning Output Format ```markdown # Feature: [Feature Name] ## Overview Brief description of the feature and its value. ## Tasks ### Phase 1: Foundation 1. **[Task Name]** (S/M/L) - Description - Files: `path/to/file.ts` - Dependencies: None - Acceptance: What "done" looks like 2. **[Task Name]** (S/M/L) - Description - Files: `path/to/file.ts` - Dependencies: Task 1 - Acceptance: What "done" looks like ### Phase 2: Core Implementation ... ### Phase 3: Polish & Testing ... ## Dependencies - External: Third-party services, APIs - Internal: Other features that must be complete first ## Risks - Risk 1: Mitigation strategy - Risk 2: Mitigation strategy ## Estimates - Phase 1: X days - Phase 2: Y days - Phase 3: Z days - Total: X+Y+Z days ``` ## The product-owner Subagent ### When to Use Use the **product-owner** subagent when you need to: - Write user stories - Define acceptance criteria - Prioritize backlog items - Validate requirements - Clarify feature scope ### What product-owner Knows The product-owner subagent understands: - User story format - Acceptance criteria patterns - Feature prioritization frameworks - User research interpretation - Business value assessment ### Example Requests **User Story Writing:** ``` "Use product-owner to write user stories for the meal planning feature. Consider different user personas: budget shoppers, health-conscious users, and busy families." ``` **Acceptance Criteria:** ``` "Use product-owner to define acceptance criteria for the price alert feature. What conditions must be met for this feature to be considered complete?" ``` **Prioritization:** ``` "Use product-owner to prioritize these feature requests based on user value and development effort: 1. Dark mode 2. Recipe suggestions based on deals 3. Store location search 4. Price history graphs" ``` ### User Story Format ```markdown ## User Story: [Short Title] **As a** [type of user] **I want to** [goal/desire] **So that** [benefit/value] ### Acceptance Criteria **Given** [context/starting state] **When** [action taken] **Then** [expected outcome] ### Additional Notes - Edge cases to consider - Related features - Out of scope items ### Technical Notes - API endpoints needed - Database changes - Third-party integrations ``` ## Documentation Organization The project organizes documentation as follows: ``` docs/ ├── adr/ # Architecture Decision Records │ ├── index.md # ADR index │ └── NNNN-title.md # Individual ADRs ├── subagents/ # Subagent guides (this directory) ├── plans/ # Implementation plans ├── tests/ # Test documentation ├── TESTING.md # Testing guide ├── BARE-METAL-SETUP.md # Production setup ├── DESIGN_TOKENS.md # Design system tokens └── ... # Other documentation ``` ## Best Practices ### 1. Keep Documentation Current Documentation should be updated alongside code changes. The `describer-for-ai` subagent can help identify what documentation needs updating after code changes. ### 2. Use Consistent Terminology Refer to entities and concepts consistently: - "Flyer" not "Ad" or "Circular" - "Store" not "Retailer" or "Shop" - "Deal" not "Offer" or "Sale" ### 3. Include Examples All documentation should include concrete examples: - API docs: Include curl commands and JSON payloads - User guides: Include screenshots or step-by-step instructions - Technical docs: Include code snippets ### 4. Cross-Reference Related Documentation Use relative links to connect related documentation: ```markdown See [Testing Guide](../TESTING.md) for test execution details. ``` ### 5. Date and Version Documentation Include dates on documentation that may become stale: ```markdown **Last Updated**: 2026-01-21 **Applies to**: v0.12.x ``` ## Related Documentation - [OVERVIEW.md](./OVERVIEW.md) - Subagent system overview - [../adr/index.md](../adr/index.md) - ADR index - [../TESTING.md](../TESTING.md) - Testing guide - [../../CLAUDE.md](../../CLAUDE.md) - AI instructions