transcription/.github/instructions/documentation-sync.instructions.md

description, applyTo

description	applyTo
Require documentation updates whenever code changes alter contracts, behavior, or scope.	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.