flyer-crawler.projectium.com/docs/subagents/DOCUMENTATION-GUIDE.md

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

### [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):

  {
    "success": true,
    "data": { ... }
  }
  

• Error (400):

  {
    "success": false,
    "error": {
      "code": "VALIDATION_ERROR",
      "message": "Description of error"
    }
  }
  

Example:

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

# 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

## 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:

See [Testing Guide](../TESTING.md) for test execution details.

5. Date and Version Documentation

Include dates on documentation that may become stale:

**Last Updated**: 2026-01-21
**Applies to**: v0.12.x

Related Documentation

• OVERVIEW.md - Subagent system overview
• ../adr/index.md - ADR index
• ../TESTING.md - Testing guide
• ../../CLAUDE.md - AI instructions