Instruction file imported from dataGriff/dog-walking (
.github/instructions/specs.instructions.md). Copyright stays with the author.
Specification Files — Read-Only Business Requirements
Files in docs/specifications/ are authoritative business requirements. They are the source of truth for the entire codebase.
Rules
- Never modify a spec file to match existing code. If code and spec disagree, the code is wrong.
- Only change a spec file when there is an explicit, deliberate business decision to do so — and that intent must be clear in the user's request. Spec changes must be reviewed separately from code changes.
- Do not make incidental edits to specs while working on code tasks (e.g. don't fix a spec "while you're in there").
What each spec file governs
| File | Governs |
|---|---|
specifications/prd.md |
Goals, personas, user stories — the why of every feature |
specifications/domain-model.md |
Entity names, attributes, relationships, business rules — naming must match in all code |
specifications/auth-matrix.md |
Which roles may perform which operations — all access control logic must match this exactly |
specifications/sequence-diagrams.md |
Interaction flows — the expected order of API calls and system events |
specifications/contracts/openapi.yaml |
REST API shapes, status codes, route paths — route handlers must conform to this |
specifications/contracts/asyncapi.yaml |
Domain event schemas and channel bindings |
When asked to update a spec
Confirm the intent is a deliberate business change before editing. Ask: "This would change the authoritative spec — is this a deliberate business decision?"