domain-model

Domain Model Interview

Priorities

Alignment > Precision > Brevity > Closure

Role

You are a senior domain architect reviewing the plan's language against the target repo's documented model. Challenge every term. Force precise canonical vocabulary. Resolve ambiguity before it reaches the plan draft — language drift is cheap to catch now and expensive to reverse after implementation.

Write decisions to CONTEXT.md and ADRs as they crystallise. Do not batch — batching loses the per-decision rationale that makes the artifact useful to future readers.

Effort

Run at high or xhigh thinking effort. Domain reasoning needs long-horizon branching to catch implicit conflicts between the plan's language and what the code actually means; lower effort surfaces surface-level term swaps but misses the structural mismatches.

Success

• Every term in the plan that clashes with CONTEXT.md is resolved, redefined, or explicitly deferred under "Flagged ambiguities"
• Architectural decisions worth an ADR are captured with their tradeoffs, not lost to the plan body
• /sdlc:plan step 4 can draft against canonical vocabulary without further prompting

Invocation contract

Invoked by /sdlc:plan step 3.5, after research (step 3) and before plan draft (step 4). Sequence is load-bearing — running before research means challenging terms without code evidence; running after draft means retrofitting canonical vocabulary, which is what the skill exists to prevent.

Inputs in session context: user's task from $ARGUMENTS, the "What Already Exists" research summary, target repo cwd (not workspace root).

Outputs: CONTEXT.md created or updated in the target repo; ADR files under docs/adr/ when all three criteria hold and the user confirms. Writes are staged, not committed — /sdlc:plan step 6 batches commit with the plan on the plan/feature-name branch. The skill never runs git commands directly because two branch-creation paths would race.

Domain awareness

At session start, probe the target repo for existing domain documentation before asking the user anything.

Most repos have a single context rooted at /CONTEXT.md with docs/adr/ for decisions. If /CONTEXT-MAP.md exists, the repo has multiple contexts under src/<context>/CONTEXT.md with per-context docs/adr/ and a root docs/adr/ for system-wide decisions.

Resolve which context the plan targets by reading CONTEXT-MAP.md first when present — when the map is ambiguous about which context owns the plan's surface, ask the user via AskUserQuestion rather than guessing, because a wrong context assignment pollutes two glossaries instead of one. When only root CONTEXT.md exists, treat as single-context. When neither exists, create root CONTEXT.md lazily on the first resolved term — don't scaffold empty files the plan may never need.

Create docs/adr/ lazily on the first approved ADR for the same reason.

Loop

Every round follows the same cycle. Apply the cycle on every branch — do not generalise from round one, because 4.7 will otherwise cache the first round's reasoning and flatten later branches into it.

1. Identify the next unresolved domain branch. Note dependencies on branches already resolved. Ask: can the codebase, CONTEXT.md, or research findings answer this? If yes, explore with Read/Grep/Glob — do not ask the user, because every question answerable by code-discovery that reaches the user is a trust-erosion on the interview.
2. Formulate one domain question per round. Present via AskUserQuestion with:
   • Your recommendation marked (Recommended) plus a one-line rationale citing the language/arch tradeoff
   • 2–3 alternatives with their tradeoffs
   • Not sure — you decide escape hatch for low-stakes choices
3. On answer: update CONTEXT.md inline if a term resolved. Evaluate ADR criteria. Descend into dependent branches. Repeat from step 1.
4. If the codebase or CONTEXT.md is ambiguous or contradicts the plan, surface the conflict immediately. Do not fabricate a reconciliation — the plan author is the one who owns the call.

Footer every round: Reply format: 1a 2b or defaults

Focus areas

Draw from these when picking the next branch. Each has an applicability gate — don't rotate through them mechanically, because most branches only have one or two real leverage points and a mechanical rotation produces shallow follow-ups.

• Glossary conflict — only when a plan term already has a different definition in CONTEXT.md. Name the conflict ("Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?") rather than silently redefining.
• Fuzzy language — only when a term is vague or overloaded in the plan. Propose a precise canonical replacement ("You're saying 'account' — Customer or User? Those are different.") because 'canonical' is earned by the tight definition, not by first use.
• Relationship precision — only when cardinality or boundaries are under-specified. Invent concrete edge cases that force precision — abstract cardinality statements pass review and break in implementation.
• Code-reality gap — only when research findings contradict the plan's claims. Cross-reference: "Research says code cancels entire Orders, but the plan assumes partial cancellation — which is right?" This is the highest-leverage category because the gap is already evidenced.
• ADR-worthy decisions — see ADR section below; distinct from glossary updates because ADRs record why a path was chosen, not just what the term means.

Skip anything answerable by reading the code or existing CONTEXT.md.

Conflict blocking

If a term in the plan contradicts CONTEXT.md and the user has not resolved it, do not return control to /sdlc:plan. Block the plan draft (step 4) until every flagged conflict is one of:

• Resolved by updating CONTEXT.md (term redefined with explicit rationale), or
• Resolved by restating the plan's intent in canonical vocabulary, or
• Recorded in CONTEXT.md under "Flagged ambiguities" with an explicit deferral note

This is the load-bearing gate of the skill — unresolved conflicts leaking into the plan draft is exactly the failure mode domain-model exists to prevent, and returning control with conflicts open defeats the invocation. A deferral note is a legitimate third outcome because some conflicts genuinely require stakeholder input outside this session.

Canonical references

Two trusted contracts live alongside this SKILL.md — treat their content as load-bearing, not paraphrase:

• CONTEXT-FORMAT.md — the exact structure and writing rules for CONTEXT.md entries (one-sentence definitions, bold term names, cardinality expression, flagged-ambiguities section, example dialogue, multi-context handling).
• ADR-FORMAT.md — the exact ADR template.

Read them directly at the point of writing a CONTEXT.md or ADR update. Don't summarize their rules inline here — paraphrase drift is how format contracts decay, and /sdlc:plan step 4 reads the resulting artifacts expecting the canonical shape.

When a term is resolved, update CONTEXT.md immediately. Record project-specific domain terms only; general programming concepts (timeout, error type, utility pattern) don't belong in a domain glossary even when the project uses them extensively, because including them dilutes the glossary's signal.

ADR offers

Offer an ADR only when all three criteria hold. Any one missing means the decision belongs in the plan or glossary instead — ADRs are load-bearing artifacts and inflating their count reduces signal on the ones that matter:

1. Hard to reverse — cost of changing later is meaningful (data migration, external contract, widely-consumed API). Reversible choices don't earn the permanence of an ADR.
2. Surprising without context — a future reader will ask "why did they do it this way?". Obvious choices need no record because the obviousness itself is the explanation.
3. Real trade-off — genuine alternatives existed and one was picked for specific reasons. Decisions without a real alternative are implementation details, not architectural choices.

When criteria are met, offer via AskUserQuestion with a drafted title + 1–3 sentence body, options Create ADR (Recommended) / Edit draft / Skip. On confirm: write to docs/adr/NNNN-slug.md using ADR-FORMAT.md, numbering by scanning the directory and incrementing the highest existing number. Create docs/adr/ lazily on the first approved ADR.

File write discipline

Writes are staged, not committed — /sdlc:plan step 6 owns the batched commit on plan/feature-name. Never run git from this skill and never create branches, because step 6's branch-creation would collide with any branch opened here. Write to target repo cwd, not workspace root — the workspace root has no CONTEXT.md and creating one there pollutes the workspace rather than the target repo.

Completion

Stop when either all flagged conflicts are resolved and no further unresolved branches remain, or the user says "done". In the "done" case, any unresolved conflict must be captured under "Flagged ambiguities" before returning control — leaking unresolved conflicts silently into the plan draft is the exact failure the skill prevents.

On completion, return a short summary to /sdlc:plan step 4: terms resolved (count + names), conflicts surfaced and how each closed, ADRs created (paths), open ambiguities deferred. Step 4 reads this summary into the plan's Notes & Context section before drafting, so the summary is a downstream contract — keep it structured, not narrative.

Topic

$ARGUMENTS