---
description: Require documentation updates whenever code changes alter contracts, behavior, or scope.
applyTo: 'src/transcription/**/*.py'
---

# Documentation Sync Requirements

Keep docs in sync in the same change whenever implementation alters a documented contract, behavior, or roadmap decision.

Documentation targets below always refer to the **current** baseline. `docs/index.md` states which
baseline that is; resolve any version-specific document from there. Never cite a superseded version
tree by name in this file or in the docs you update — retired revision trees are not authority, and
`tests/test_meta_contract_guards.py` fails active contract files that route authority through them.

## Update documentation when any of these change

1. **Schema/Data contract**
   - Models, fields, enums, constraints, indexes, relationships, loading semantics.
   - **Required doc update:** `docs/schema.md`.

2. **Configuration contract**
   - `Settings` keys, defaults, required/optional environment values.
   - **Required doc update:** `.env.production.example` and any directly related setup docs.

3. **User-visible UI behavior**
   - Page flow, routes, button/action behavior, labels, status wording, empty/error states.
   - **Required doc update:** relevant `docs/ui/pages/*.md` docs and feature docs when applicable.

4. **Error handling semantics**
   - Error categories, retry behavior, envelope structure, translation boundaries.
   - **Required doc update:** `docs/error_handling.md` and `docs/invariant/error_handling.md`.

5. **Roadmap/scope decisions**
   - Version targets, sequencing, deferrals, and accepted alternatives.
   - **Required doc update:** `docs/roadmap_plan.md`, plus any backlog or feature document for the
     current baseline. Locate it through `docs/index.md` rather than assuming a version-named path.

## Working rule

If none of the categories above changed, documentation edits are optional.
If any category changed, update docs in the same PR/change set rather than deferring.