doc updates and test fixin

2026-01-22 11:17:06 -08:00
parent 9f7b821760
commit fac98f4c54
56 changed files with 11967 additions and 357 deletions
--- a/docs/subagents/DOCUMENTATION-GUIDE.md
+++ b/docs/subagents/DOCUMENTATION-GUIDE.md
@@ -0,0 +1,412 @@
+# 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