ThothII/docs/agents/domain.md

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

/
├── 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.