Feature Domain Expert

# feature-domain-expert

> Authoritative guide for authoring and consuming feature knowledge files in `ai-context/features/`.

**Triggers**: feature file, domain knowledge, ai-context/features, bounded context, business rules,
feature-domain-expert, domain invariants, domain context, feature doc

---

## Patterns

### Pattern 1: Feature file vs. SDD spec — the critical distinction

These two file types serve fundamentally different purposes and MUST NOT duplicate each other's
content:

| Aspect | `ai-context/features/<domain>.md` | SDD spec (engram artifact) |
|--------|----------------------------------|----------------------------------|
| **Purpose** | Permanent business domain knowledge | Behavioral delta spec for a specific change |
| **Lifetime** | Lives forever — updated but never deleted | Created per change — eventually archived |
| **Content** | Business rules, invariants, data model, integration contracts, history | GIVEN/WHEN/THEN scenarios describing observable behavior for one change |
| **When written** | Once per bounded context; updated via `/memory-update` | Once per SDD change; archived with the change |
| **Who reads it** | `sdd-propose` Step 0, `sdd-spec` Step 0, human developers | `sdd-apply` (acceptance criteria), `sdd-verify` |
| **Cross-change value** | High — encodes knowledge that predates and outlasts any single change | Low — describes behavior introduced or modified by one specific change |

**Rule**: if you are writing GIVEN/WHEN/THEN scenarios, it belongs in a SDD spec artifact. If you
are writing a business rule that will still be true five SDD cycles from now, it belongs in
`ai-context/features/`.

---

### Pattern 2: When to create a feature file

Create a new `ai-context/features/<domain>.md` when ALL of the following are true:

1. A bounded context (a coherent area of business logic with its own vocabulary) has been
   identified — either by working in it during an SDD cycle or during `memory-init`.
2. The domain has at least one business rule or invariant that is not captured in any spec file and
   that future SDD phases should know about.
3. The domain is likely to be touched again in future SDD cycles (i.e., it is not a one-off
   technical implementation detail).

Do NOT create a feature file for:
- Pure infrastructure concerns with no business rules (e.g., CI pipeline configuration).
- A domain whose knowledge is already fully expressed in a small, stable spec file that will never
  be archived.
- Domains that have not yet been explored — create a stub via `memory-init` and leave sections
  empty until knowledge is acquired.

---

### Pattern 3: What belongs in each of the six sections

The canonical six sections in order — every feature file must contain all six:

**1. Domain Overview**
Write 2–4 sentences describing what the bounded context does, who owns it, and what core
responsibility it holds in the system. Focus on purpose and scope, not implementation details.

**2. Business Rules and Invariants**
List the always-true constraints the domain enforces regardless of code path. Each item is a
declarative statement that would still hold even if the implementation were rewritten from scratch.
Examples: "A refund cannot exceed the original payment amount." "A user must have a verified email
before making a purchase."

**3. Data Model Summary**
Describe key entities, their relationships, and critical field constraints in plain prose or a
small table. This is not a full schema — orient the reader to the most important entities and their
constraints. Relationships between entities belong here.

**4. Integration Points**
Document every external system, service, or domain this bounded context depends on or exposes an
interface to. Us