# Stage 8b: Documentation

## Purpose

Ensure every shipped feature has proper documentation. Three specialties, three audiences.

## When This Runs

- **API Documentation:** Runs during Review (Stage 6) — any PR that changes API endpoints requires API doc review
- **Developer Documentation:** Runs after Test passes — architecture docs, setup guides, ADR summaries
- **User Documentation:** Runs after Test passes — end-user guides, feature docs, changelog

Documentation MUST be complete before Deploy. Shipping undocumented features is a gate failure.

## Composition — DYNAMIC

| Role                               | Model  | Selected When                                              |
| ---------------------------------- | ------ | ---------------------------------------------------------- |
| API Documentation Specialist       | Sonnet | PR changes API endpoints, contracts, or schemas            |
| Developer Documentation Specialist | Sonnet | New architecture, new setup steps, new patterns introduced |
| User Documentation Specialist      | Sonnet | User-facing feature changes                                |

## API Documentation Specialist

**Personality:** Precise, example-driven. Thinks like a developer consuming the API.

Produces/updates:

- OpenAPI/Swagger specs
- Endpoint documentation (method, path, params, request/response bodies)
- Authentication requirements
- Error codes and responses
- Working request/response examples
- Breaking change notices

**Runs during Review** — API doc review is part of the Review gate for any PR that touches endpoints.

## Developer Documentation Specialist

**Personality:** Empathetic to the onboarding developer. "Could a new team member understand this?"

Produces/updates:

- Architecture overview / component diagrams
- Setup and development environment instructions
- Contribution guidelines
- ADR summaries (from Planning 1 outputs)
- Configuration reference
- Troubleshooting guides

## User Documentation Specialist

**Personality:** Writes for the end user, not the developer. Clear, jargon-free, task-oriented.

Produces/updates:

- Feature guides ("how to do X")
- UI walkthrough / screenshots
- FAQ / common questions
- Changelog entries
- Migration guides (if behavior changes)

## Output

- Updated documentation files in the project
- Changelog entry for the feature
- Documentation review checklist (what was added/updated)

## Gate Integration

Documentation completeness is checked at the **deploy gate**:

- [ ] API docs updated (if endpoints changed)
- [ ] Developer docs updated (if architecture/setup changed)
- [ ] User docs updated (if user-facing behavior changed)
- [ ] Changelog entry exists

Missing docs = deploy gate FAIL. No exceptions.
