TorbatYar/docs/ai-framework/documentation-template.md

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).

Update Checklist

Always

• Phase document created/updated (from phase-template.md)
• phase-handover.md sections filled (or equivalent in phase doc)
• progress.md — completed work only
• next-steps.md — immediate next milestone only
• module-registry.md — version, phase, events, permissions, migration
• phase-manifest.yaml — status / dependencies
• service-manifest.yaml — version / phase / APIs / events if service changed

When Applicable

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

Never

• Do not put future work into progress.md
• Do not overwrite accepted ADRs
• Do not duplicate master-prompt.md rules into phase prompts
• Do not leave broken links or undocumented public surfaces for the phase

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 framework loop/gates when the phase is AI-implemented
• Progress / next-steps

Validation

Before completion, run Documentation + Cross Reference + Broken Link validation from quality-gates.md.

Related Documents

• docs/README.md
• Phase Template
• Phase Handover
• templates/ (registry-oriented short templates)