# Documentation Template

How documentation must be updated after every phase.

## Principle

Code and documentation ship together. A phase that changes behavior without docs is incomplete ([project-principles.md](../development/project-principles.md)). Enterprise completeness requires documentation completeness ([enterprise-completeness.md](enterprise-completeness.md)).

## Update Checklist

### Always

- [ ] Phase document created/updated (from [phase-template.md](phase-template.md)) including Enterprise Phase Discovery Record, Business Analysis, and Domain Model
- [ ] [phase-handover.md](phase-handover.md) sections filled (or equivalent in phase doc) including Discovery summary, Enterprise Completeness Sign-Off, and Definition of Done
- [ ] [progress.md](../progress.md) — completed work only
- [ ] [next-steps.md](../next-steps.md) — immediate next milestone only
- [ ] [module-registry.md](../module-registry.md) — version, phase, events, permissions, migration
- [ ] [phase-manifest.yaml](phase-manifest.yaml) — status / dependencies
- [ ] [service-manifest.yaml](service-manifest.yaml) — version / phase / APIs / events if service changed
- [ ] OpenAPI reflects new/changed routes (for API phases)

### When Applicable

- [ ] [roadmap.md](../roadmap.md) — only if future sequencing changed
- [ ] [provider-registry.md](../provider-registry.md) — new/changed providers
- [ ] [glossary.md](../glossary.md) — new canonical terms
- [ ] ADR created/updated under [architecture/adr/](../architecture/adr/)
- [ ] Architecture docs if boundaries/topology changed (never silently)
- [ ] [reference/api-reference.md](../reference/api-reference.md)
- [ ] [reference/services-contracts.md](../reference/services-contracts.md)
- [ ] [reference/event-catalog.md](../reference/event-catalog.md)
- [ ] [reference/database-schema.md](../reference/database-schema.md)
- [ ] Service README under `backend/services/<name>/`
- [ ] Phase area README under [phases/](../phases/)
- [ ] Frontend docs under [frontend/](../frontend/) if UI shipped
- [ ] Mandatory artifact N/A justifications recorded

### Never

- Do not put future work into `progress.md`
- Do not overwrite accepted ADRs
- Do not duplicate [master-prompt.md](master-prompt.md) / DoD / completeness rules into phase prompts
- Do not leave broken links or undocumented public surfaces for the phase
- Do not mark Complete while documenting missing current-phase artifacts as “limitations”

## Cross-Link Requirements

Every new phase doc must link at least:

- Architecture overview or relevant architecture leaf
- Related ADR(s)
- Module registry entry
- Development standards (principles / testing) as needed
- AI/Enterprise framework: Discovery, loop, gates, DoD (when AI-implemented)
- Progress / next-steps

## Validation

Before completion, run Documentation + Cross Reference + Broken Link validation from [quality-gates.md](quality-gates.md), and confirm Enterprise Completeness documentation dimension.

## Related Documents

- [docs/README.md](../README.md)
- [Phase Template](phase-template.md)
- [Phase Handover](phase-handover.md)
- [Definition of Done](definition-of-done.md)
- [Enterprise Phase Discovery](enterprise-phase-discovery.md)
- [Enterprise Completeness](enterprise-completeness.md)
- [templates/](../templates/) (registry-oriented short templates)