3.0 KiB
3.0 KiB
Shared Language
Use this page to keep the repository's ubiquitous language stable. It is the project-wide glossary for terms that should mean one thing everywhere in design artifacts, code, tests, and reviews.
Why this exists
Naming inconsistency creates design inconsistency. When the same concept is called three different things, reviewers and LLMs start inventing distinctions that are not real. A stable shared language improves design quality, review quality, and implementation consistency.
This file is for project-wide terms. Feature-specific naming choices should also be recorded in the relevant design artifact.
How to use it
- Add terms that appear across multiple features or modules.
- Prefer short domain definitions over implementation detail.
- Record preferred terms and rejected synonyms.
- Update this file when the team decides one name should win.
- Keep the grammar consistent with the naming rules in
../explanation/naming-for-domain-modeling.md.
Core grammar
- Commands: imperative intents such as
LoadPackage - Events: past-tense facts such as
PackageLoaded - States / Objects: domain nouns such as
LoadingTruck - Workflows: verb-noun names such as
loadPackage - Policies: decision-oriented names such as
decideLoadEligibility
Project-wide glossary template
| Term | Meaning | Use this, not that | Notes |
|---|---|---|---|
Recovery Pipeline |
Release-oriented workflow that turns one upstream snapshot into a buildable, browsable recovered tree and release artifacts | Recovery Pipeline not deobfuscation script chain |
Feature-level umbrella term used across contexts. |
Recovered Tree |
Canonical editable source tree emitted at repo root for review and modification | Recovered Tree not original repo layout |
The tree is reconstructed for usability, not historical fidelity. |
Build-first |
Acceptance rule that preserves buildability even when readability improvements are still incomplete | Build-first not runtime complete |
Current hard success invariant for the feature. |
Review-needed Artifact |
Machine-readable report plus concise human summary that surfaces uncertainty, failure, or conflict | Review-needed Artifact not warning log |
Explicit inspection seam rather than hidden failure. |
Maintained Transform |
Durable replayable local change stored outside the numbered upstream-processing phases | Maintained Transform not manual patch |
Reused by replay and release contexts. |
Naming Memory |
Small reviewable history of accepted recovered names reused in later relabel iterations | Naming Memory not rename cache |
Shared iterative-naming term with reviewer-facing meaning. |
Review questions
- Would a domain expert recognize these terms?
- Are the same concepts named consistently across story, events, model, code, and tests?
- Are we accidentally using programmer words where domain words should exist?
- Have we documented which synonym is preferred when multiple names are plausible?