Reference Over Duplication
Each fact is stated once, where it is maintained, and every other place that needs it points there instead of keeping a copy.
- Kind
- Convention
- Domain
- Documentation & Metadata
- Applies at
./- Status
- Stable
- Source
.descriptor/README.md
01 Defines
The rule that a repository has one source of truth per fact: metadata, navigation, and documentation identify things and link to where they are defined, rather than restating details that can drift.
02 Applies when
- A second file needs a fact that another file already owns — a deployment setting, an API shape, a directory’s rules.
- Summary or index documents are written over areas that have their own documentation.
- Several readers — people, catalog systems, automation — need the same information.
03 Boundaries
- A short identifying phrase or a link is a reference, not a duplicate.
- Generated copies, such as staged documentation or managed standard files, are acceptable because one source regenerates them.
- Operational and domain-specific detail stays in its existing source of truth.
Expected behaviour
- 01Indexes and metadata identify a resource and point at the file or system that defines it.
- 02Information that can be resolved through a reference is not represented in a second location.
- 03Summary pages say what an area is for and where to go next, and stop there.
- 04When a copy is unavoidable, it is generated from the source and never edited directly.
Behaviour#
Every copy of a fact is a promise to keep two places in step. Promises like that are broken quietly: one file is updated, the other is not, and a reader can no longer tell which is current. The repository avoids making the promise. A fact lives with the thing that owns it, and everything else links.
- 01 Index The code map, a descriptor, or a summary names the thing Code Map
- 02 Reference A link or path points at its owner
- 03 Source of truth The owner — a README, a make module, a Terraform root, an API definition — holds the detail Owner Documentation
What drift looks like#
The problem statement for this repository lists the symptoms of losing this discipline. Human-facing docs, the generated code map, and the actual layout drifted apart. It became hard to tell which files were externally managed, which were repository-specific, and which were meant to be reused. The conclusion: a repository cannot be a trustworthy reference “if readers must reverse-engineer which source of truth is current.”
Reference
- A descriptor points at
./openapi.yaml - The code map links to
www/README.md - A deployment guide links to
scripts/deploy.sh - A decision record lists the files that express it
Duplicate
- Deployment settings copied into catalog metadata
- Area rules restated in a top-level overview
- Command behaviour re-explained in workflow YAML
- A decision described in prose with no pointer to code
Examples#
The catalog-descriptor rules state the convention most directly:
- Reference authoritative definitions and configuration where they already exist
rather than duplicating their contents in catalog descriptors.
- Avoid representing the same information in multiple locations when it can
instead be resolved through a reference.
The code map applies the same rule to navigation, and says so at the top:
“This page only says what each area is for and where to go next.” The detail
stays in each area’s README.md.
Connections