domain.md - AiToEarn

domain.md

1	# Domain Docs
2
3	How the engineering skills should consume this repo's domain documentation when exploring the codebase.
4
5	## Before exploring, read these
6
7	- `CONTEXT.md` at the repo root, or
8	- `CONTEXT-MAP.md` at the repo root if it exists — it points at one `CONTEXT.md` per context. Read each one relevant to the topic.
9	- `docs/adr/` — read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
10
11	If any of these files don't exist, proceed silently. Don't flag their absence; don't suggest creating them upfront. The producer skill (`/grill-with-docs`) creates them lazily when terms or decisions actually get resolved.
12
13	## File structure
14
15	Single-context repo (most repos):
16
17	```
18	/
19	├── CONTEXT.md
20	├── docs/adr/
21	│ ├── 0001-event-sourced-orders.md
22	│ └── 0002-postgres-for-write-model.md
23	└── src/
24	```
25
26	Multi-context repo (presence of `CONTEXT-MAP.md` at the root):
27
28	```
29	/
30	├── CONTEXT-MAP.md
31	├── docs/adr/ ← system-wide decisions
32	└── src/
33	├── ordering/
34	│ ├── CONTEXT.md
35	│ └── docs/adr/ ← context-specific decisions
36	└── billing/
37	├── CONTEXT.md
38	└── docs/adr/
39	```
40
41	## Use the glossary's vocabulary
42
43	When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.
44
45	If the concept you need isn't in the glossary yet, that's a signal — either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/grill-with-docs`).
46
47	## Flag ADR conflicts
48
49	If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
50
51	> _Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…_
52

52 lines MARKDOWN