| id | DEV-335 | |
|---|---|---|
| title | Keep Each Fact in One Canonical Place | |
| status | active | |
| enforcement | manual | |
| severity | error | |
| depends_on |
|
When the same fact is copied into several files, or restated from a system that owns it, the copies drift apart as one changes and the others do not. Readers cannot tell which copy is current, and each is a chance to be wrong.
Every fact has exactly one canonical home; everywhere else references that home instead of copying it. A copy is a second source of truth that will drift, so the goal is to make sure there is only ever one.
- Keep each fact (a procedure, template, configuration step, or value) in exactly one file, and link to it from anywhere else that needs it rather than restating it.
- When a fact belongs to another system (bot commands, third-party APIs, another service's config), treat that system's own documentation as its canonical home and link it, instead of restating details that change without notice. For example, DEV-140 links the Wizard command docs rather than hardcoding a command string.
A good and bad shape for the same fact:
Good: To set an ETA, use the [Wizard commands](https://wizard.holdex.io/docs/commands).
Bad: To set an ETA, comment `@holdex issue set-eta <date>` on the Goal.- Each fact lives in exactly one file; other places link to it, not copy it
- No fact is duplicated across files
- Facts owned by another system link to that system's canonical documentation rather than restating them