| name | domain-modeling |
| description | Maintain a repository's domain vocabulary and architecture decision records. Use when Codex needs to sharpen terminology, resolve ambiguous domain concepts, update CONTEXT.md, create ADRs, or support grill-with-docs, triage, TDD, diagnosis, or architecture work with durable domain language. |
Domain Modeling
Actively sharpen the project's domain model while discussing or designing work. This skill changes durable domain docs; merely reading CONTEXT.md is not domain modeling.
Read docs/agents/domain.md if it exists.
Files
Most repos use:
CONTEXT.md at the repo root.docs/adr/ for architecture decision records.
Monorepos may use CONTEXT-MAP.md pointing to multiple context-local CONTEXT.md files.
Create files lazily only when there is something real to record.
Use:
Workflow
1. Detect Language Pressure
Use this skill when:
- A term is vague, overloaded, or conflicts with existing glossary language.
- User language and code language disagree.
- A design depends on a domain distinction that should survive chat context.
- A decision is hard to reverse, surprising without context, and based on real trade-offs.
2. Challenge And Resolve
Ask focused questions one at a time. Prefer concrete scenarios over abstract definitions.
When code contradicts the user's description, surface the conflict and ask which is authoritative.
3. Update Durable Docs
When a term is resolved, update the relevant CONTEXT.md immediately. Keep it as glossary only:
- Domain concepts and preferred names.
- Short definitions.
- Avoided synonyms.
Do not store feature requirements, implementation plans, issue status, or scratch notes in CONTEXT.md.
4. Offer ADRs Sparingly
Offer an ADR only when all are true:
- Hard to reverse.
- Surprising without context.
- Based on a real trade-off.
Keep ADRs short. Record the decision and why it exists.
Finish
Summarize changed terms or ADRs and mention any unresolved language risks.
