/ddd-refiner

name: ddd-refiner
description: "Facilitate a structured conversation to define DDD guardrails for domain design within a repository. Produces a formal ddd-principles.md document that the domain-driven-design atom will use as its override. Use when setting up domain design principles, defining aggregate rules, or when the user says 'setup DDD', 'define domain rules', 'DDD principles', or 'help me define my domain patterns'."

DDD Refiner

What This Produces

• **Output**: `.lattice/standards/ddd-principles.md` (or custom path from `.lattice/config.yaml` → `paths.ddd_principles`)
• **Two modes**:
• **Overlay** (`mode: overlay`): A slim document containing only sections that differ from the defaults. The domain-driven-design atom reads its embedded defaults first, then applies this document's sections on top. This is the expected common case.
• **Override** (`mode: override`): A comprehensive standalone document that fully replaces the atom's embedded defaults. For teams with fundamentally different domain modeling principles.
• **Default mode**: Overlay -- produces only what the user wants to change
• **Config key**: `paths.ddd_principles` in `.lattice/config.yaml`
• **Template**: Read `./assets/template.md` for the full document structure, default content, and interview guidance comments

Scope Clarification

This skill defines the *rules of domain crafting*, not the domain model itself. The domain model evolves through features; this document defines the guardrails. It covers DDD tactical patterns only -- not strategic DDD (no context mapping, no microservice topology, no bounded context integration).

Before You Begin

Check for existing documents

Before starting the interview, check whether a custom document already exists:

1. Read `.lattice/config.yaml` -- does `paths.ddd_principles` point to a file? 2. If yes, read that file. Ask the user:

• "You already have a custom DDD principles document. Would you like to **revise** it (update specific sections), **start fresh** (new interview), or **add to it** (add new sections)?"
• Revise: Load the existing document, walk through only the sections the user wants to change, and update in place.
• Start fresh: Proceed with the full interview flow below.
• Add to it: Skip to the "New Sections" part of the interview.

3. If no config or no existing document, proceed with the full interview flow.

Scan the repository

Look for signals that inform the conversation:

• **Domain folder**: Does a `domain/` (or `core/`, `model/`) folder exist? What's inside it?
• **Existing aggregates**: Are there entities, value objects, aggregate roots? How are they structured?
• **Anemic patterns**: Are entities data holders or do they have behavior?
• **Identity patterns**: Typed IDs, raw UUIDs, database-generated IDs?
• **Event patterns**: Are domain events used? What naming convention?
• **Architecture docs**: Any existing DDD documentation, ADRs, domain glossaries?

Share relevant findings with the user at the start: "I noticed your project already has [X patterns]. I'll use that as context."

If the project is new with no code, proceed with pure defaults as the starting point.

Choosing the Mode

The first decision in the conversation. Present the three options:

"How would you like to define your DDD principles?

1. **Customize specific sections** (overlay) -- Keep the defaults and change only what differs for your project. This produces a slim document. Most teams choose this. 2. **Define everything from scratch** (override) -- Walk through all sections and produce a comprehensive standalone document. 3. **Add project-specific sections only** (overlay with additions) -- Keep all defaults as-is and add new sections for your team's specific rules (e.g., ubiquitous language glossary, bounded context boundaries).

The defaults cover standard DDD tactical patterns well. Option 1 is recommended unless your domain modeling approach is fundamentally different."

Map the choice:

• Options 1 and 3 → `mode: overlay`
• Option 2 → `mode: override`

Facilitation Approach

Conversation style

• **One section at a time.** Do not dump all questions at once. Walk through the template sequentially.
• **Defaults-first.** For each section, briefly summarize the default, then ask if it matches. Do not read the entire default verbatim -- summarize the key points and ask.
• **Record decisions, not discussion.** The output document reads as a specification, not meeting notes. "We discussed X and decided Y" is wrong. "Y" is right.
• **Probe, don't interrogate.** Use the probing questions in the template guidance comments as follow-ups when the user's answer is ambiguous, not as a checklist.

For overlay mode

This should be fast. Many sections will be "keep as-is."

1. Present each section's default briefly (a 2-3 sentence summary, not full content). 2. Ask: "Does this match your project, or would you like to change it?" 3. If the user says it matches → skip it (section will NOT appear in the output). 4. If the user wants changes → dive into that section, discuss the specifics, record the changes. 5. At the end, ask: "Any sections you'd like to add that aren't in the defaults?" (e.g., ubiquitous language glossary, bounded context scope). 6. Only sections the user changed or added appear in the output document.

For override mode

This is thorough. Every section gets attention and appears in the output.

1. Walk through every section in full detail. 2. User confirms, modifies, or replaces each section. 3. All sections appear in the output -- defaults for unchanged ones, user's version for changed ones.

Common scenarios

• **"I agree with everything"** → No custom document needed. Tell the user: "The embedded defaults are already active and match your preferences. No custom document is needed -- the domain-driven-design atom will use the defaults automatically."
• **"I agree except one section"** → Overlay mode, intervie