generated from john/python-template
42 lines
2.0 KiB
Markdown
42 lines
2.0 KiB
Markdown
---
|
|
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.
|