57 lines
2.1 KiB
Markdown
57 lines
2.1 KiB
Markdown
|
# Domain Documentation
|
||
|
|
|
||
|
|
This project follows the domain documentation conventions used by the `interrogate` skill.
|
||
|
|
|
||
|
|
## Expected Layout
|
||
|
|
|
||
|
|
### Single-context (most common)
|
||
|
|
```
|
||
|
|
/ (project root)
|
||
|
|
├── CONTEXT.md ← canonical glossary and domain model
|
||
|
|
├── docs/
|
||
|
|
│ └── adr/ ← Architectural Decision Records
|
||
|
|
│ ├── 0001-....md
|
||
|
|
│ └── ...
|
||
|
|
└── src/ (or equivalent)
|
||
|
|
```
|
||
|
|
|
||
|
|
### Multi-context (monorepos or large systems)
|
||
|
|
```
|
||
|
|
/ (project root)
|
||
|
|
├── CONTEXT-MAP.md ← points to per-context locations
|
||
|
|
├── docs/
|
||
|
|
│ └── adr/ ← system-wide ADRs
|
||
|
|
├── src/
|
||
|
|
│ ├── context-a/
|
||
|
|
│ │ ├── CONTEXT.md
|
||
|
|
│ │ └── docs/adr/
|
||
|
|
│ └── context-b/
|
||
|
|
│ ├── CONTEXT.md
|
||
|
|
│ └── docs/adr/
|
||
|
|
```
|
||
|
|
|
||
|
|
## Rules for Skills and Agents
|
||
|
|
|
||
|
|
### Lazy Creation
|
||
|
|
- Only create `CONTEXT.md` when the first meaningful term is resolved.
|
||
|
|
- Only create `docs/adr/` (or per-context ADR folders) when the first ADR is actually needed.
|
||
|
|
- Do not pre-create empty files "just in case".
|
||
|
|
|
||
|
|
### During Work (especially with `interrogate`)
|
||
|
|
- When a term is used that conflicts with existing language in `CONTEXT.md`, call it out immediately.
|
||
|
|
- When vague or overloaded terms appear, propose a precise canonical term.
|
||
|
|
- Stress-test domain relationships with concrete scenarios.
|
||
|
|
- Cross-check stated behavior against actual code.
|
||
|
|
- **Update `CONTEXT.md` inline** as decisions are made — do not batch updates.
|
||
|
|
|
||
|
|
### Architectural Decision Records (ADRs)
|
||
|
|
Only propose creating an ADR when **all three** are true:
|
||
|
|
1. The decision is hard to reverse later.
|
||
|
|
2. A future reader would be surprised without the context.
|
||
|
|
3. There were genuine alternatives and a real trade-off was made.
|
||
|
|
|
||
|
|
Use the format defined in your project's ADR template when creating one.
|
||
|
|
|
||
|
|
## For Other Skills
|
||
|
|
Skills such as `interrogate`, `to-prd`, architecture review, diagnosis, and TDD should read this file (and the referenced `CONTEXT.md` / ADRs) to maintain consistent domain language across the project.
|