77 lines
2.3 KiB
Markdown
77 lines
2.3 KiB
Markdown
# Domain documentation
|
|
|
|
This repository uses a single-context domain-documentation layout.
|
|
|
|
## Sources
|
|
|
|
Before changing behavior or terminology, read:
|
|
|
|
1. `CONTEXT.md` at the repository root;
|
|
2. any relevant architectural decision records under `docs/adr/`;
|
|
3. the implementation and tests for the affected module.
|
|
|
|
`CONTEXT.md` contains the shared domain vocabulary and the system's main
|
|
concepts. Use its terminology consistently in code, documentation, issues, and
|
|
user-facing explanations.
|
|
|
|
ADRs explain important architectural decisions and their rationale. They are
|
|
created only when a durable decision needs to be recorded; the absence of
|
|
`docs/adr/` is not an error.
|
|
|
|
If one of these optional sources does not exist, continue without reporting an
|
|
error.
|
|
|
|
## Layout
|
|
|
|
```text
|
|
/
|
|
├── CONTEXT.md
|
|
└── docs/
|
|
└── adr/
|
|
└── <decision>.md
|
|
```
|
|
|
|
Do not introduce `CONTEXT-MAP.md` unless the repository later becomes a
|
|
genuine multi-context system whose domains require separate context documents.
|
|
|
|
## Working with domain concepts
|
|
|
|
When implementing or reviewing work:
|
|
|
|
- identify the domain concepts involved;
|
|
- reuse the names defined in `CONTEXT.md`;
|
|
- distinguish domain rules from infrastructure details;
|
|
- avoid creating synonyms for established terms;
|
|
- update `CONTEXT.md` when a new durable concept is introduced or an existing
|
|
definition materially changes.
|
|
|
|
For ThothII, the Evidence module and its concepts belong to this shared domain
|
|
context even though Evidence is implemented as an autonomous workflow module.
|
|
|
|
## Architectural decisions
|
|
|
|
Create an ADR when a decision:
|
|
|
|
- affects multiple parts of the system;
|
|
- establishes a durable constraint;
|
|
- selects between meaningful alternatives;
|
|
- would otherwise be difficult to reconstruct later.
|
|
|
|
Do not create an ADR for routine implementation details.
|
|
|
|
If current code or a proposed change conflicts with an ADR, flag the conflict
|
|
explicitly. Do not silently override the recorded decision.
|
|
|
|
## Keeping documentation aligned
|
|
|
|
When a change affects the domain model:
|
|
|
|
1. update the implementation;
|
|
2. update the relevant tests;
|
|
3. update `CONTEXT.md`;
|
|
4. add or update an ADR when the decision is architectural;
|
|
5. update linked plans and GitHub issues.
|
|
|
|
The persisted repository documentation, not the chat transcript, is the
|
|
long-term source of truth.
|