Add DOMAIN-AWARENESS.md and update SKILL.md files to reference it for code exploration

skills/engineering/diagnose/SKILL.md

@@ -7,6 +7,8 @@ description: Disciplined diagnosis loop for hard bugs and performance regression
 
 A discipline for hard bugs. Skip phases only when explicitly justified.
 
+Before exploring the codebase, follow [../grill-with-docs/DOMAIN-AWARENESS.md](../grill-with-docs/DOMAIN-AWARENESS.md). Use the `CONTEXT.md` vocabulary to get a clear mental model of the relevant modules.
+
 ## Phase 1 — Build a feedback loop
 
 **This is the skill.** Everything else is mechanical. If you have a fast, deterministic, agent-runnable pass/fail signal for the bug, you will find the cause — bisection, hypothesis-testing, and instrumentation all just consume that signal. If you don't have one, no amount of staring at code will save you.

skills/engineering/github-triage/SKILL.md

@@ -82,7 +82,7 @@ Before presenting anything to the maintainer:
 
 - Read the full issue: body, all comments, all labels, who reported it, when
 - If there are prior triage notes comments (from previous sessions), parse them to understand what has already been established
-- Explore the codebase to build context — understand the domain, relevant interfaces, and existing behavior related to the issue
+- Explore the codebase to build context — understand the domain, relevant interfaces, and existing behavior related to the issue. Before exploring, follow [../grill-with-docs/DOMAIN-AWARENESS.md](../grill-with-docs/DOMAIN-AWARENESS.md).
 - Read `.out-of-scope/*.md` files and check if this issue matches or is similar to a previously rejected concept
 
 ### Step 2: Present a recommendation

skills/engineering/grill-with-docs/DOMAIN-AWARENESS.md

@@ -0,0 +1,51 @@
+# Domain Awareness
+
+Consumer rules for any skill that explores a codebase. Producer rules (writing `CONTEXT.md`, offering ADRs) live in [SKILL.md](./SKILL.md).
+
+## Before exploring, read these
+
+- **`CONTEXT.md`** at the repo root, or
+- **`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.
+- **`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.
+
+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.
+
+## File structure
+
+Single-context repo (most repos):
+
+```
+/
+├── CONTEXT.md
+├── docs/adr/
+│   ├── 0001-event-sourced-orders.md
+│   └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+Multi-context repo (presence of `CONTEXT-MAP.md` at the root):
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/adr/                          ← system-wide decisions
+└── src/
+    ├── ordering/
+    │   ├── CONTEXT.md
+    │   └── docs/adr/                  ← context-specific decisions
+    └── billing/
+        ├── CONTEXT.md
+        └── docs/adr/
+```
+
+## Use the glossary's vocabulary
+
+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.
+
+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`).
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
+
+> _Contradicts ADR-0007 (event-sourced orders) — but worth reopening because…_

skills/engineering/improve-codebase-architecture/SKILL.md

@@ -26,18 +26,13 @@ Key principles (see [LANGUAGE.md](LANGUAGE.md) for the full list):
 - **The interface is the test surface.**
 - **One adapter = hypothetical seam. Two adapters = real seam.**
 
-This skill is _informed_ by the project's domain model — `CONTEXT.md` and any `docs/adr/`. The domain language gives names to good seams; ADRs record decisions the skill should not re-litigate. See [CONTEXT-FORMAT.md](../grill-with-docs/CONTEXT-FORMAT.md) and [ADR-FORMAT.md](../grill-with-docs/ADR-FORMAT.md).
+This skill is _informed_ by the project's domain model. The domain language gives names to good seams; ADRs record decisions the skill should not re-litigate.
 
 ## Process
 
 ### 1. Explore
 
-Read existing documentation first:
+Before exploring, follow [../grill-with-docs/DOMAIN-AWARENESS.md](../grill-with-docs/DOMAIN-AWARENESS.md) — read `CONTEXT.md` and relevant ADRs first.
-
-- `CONTEXT.md` (or `CONTEXT-MAP.md` + each `CONTEXT.md` in a multi-context repo)
-- Relevant ADRs in `docs/adr/` (and any context-scoped `docs/adr/` directories)
-
-If any of these files don't exist, proceed silently — don't flag their absence or suggest creating them upfront.
 
 Then use the Agent tool with `subagent_type=Explore` to walk the codebase. Don't follow rigid heuristics — explore organically and note where you experience friction:
 

skills/engineering/tdd/SKILL.md

@@ -44,6 +44,8 @@ RIGHT (vertical):
 
 ### 1. Planning
 
+Before exploring the codebase, follow [../grill-with-docs/DOMAIN-AWARENESS.md](../grill-with-docs/DOMAIN-AWARENESS.md). Test names and interface vocabulary should match the project's `CONTEXT.md`.
+
 Before writing any code:
 
 - [ ] Confirm with user what interface changes are needed

skills/engineering/to-issues/SKILL.md

@@ -15,7 +15,7 @@ Work from whatever is already in the conversation context. If the user passes a
 
 ### 2. Explore the codebase (optional)
 
-If you have not already explored the codebase, do so to understand the current state of the code.
+If you have not already explored the codebase, do so to understand the current state of the code. Before exploring, follow [../grill-with-docs/DOMAIN-AWARENESS.md](../grill-with-docs/DOMAIN-AWARENESS.md). Issue titles and descriptions should use the project's `CONTEXT.md` vocabulary.
 
 ### 3. Draft vertical slices
 

skills/engineering/to-prd/SKILL.md

@@ -7,7 +7,7 @@ This skill takes the current conversation context and codebase understanding and
 
 ## Process
 
-1. Explore the repo to understand the current state of the codebase, if you haven't already.
+1. Explore the repo to understand the current state of the codebase, if you haven't already. Before exploring, follow [../grill-with-docs/DOMAIN-AWARENESS.md](../grill-with-docs/DOMAIN-AWARENESS.md). Use the project's `CONTEXT.md` vocabulary throughout the PRD.
 
 2. Sketch out the major modules you will need to build or modify to complete the implementation. Actively look for opportunities to extract deep modules that can be tested in isolation.
 

skills/engineering/zoom-out/SKILL.md

@@ -4,4 +4,6 @@ description: Tell the agent to zoom out and give broader context or a higher-lev
 disable-model-invocation: true
 ---
 
-I don't know this area of code well. Go up a layer of abstraction. Give me a map of all the relevant modules and callers.
+I don't know this area of code well. Go up a layer of abstraction. Give me a map of all the relevant modules and callers, using the language in `CONTEXT.md`.
+
+Use [../grill-with-docs/DOMAIN-AWARENESS.md](../grill-with-docs/DOMAIN-AWARENESS.md) as a reference for how to use `CONTEXT.md`.