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

````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