Feature Domain Expert

<!-- MEMORY-CONTRACT v1 -->

Memory contract

Standing contract for every invocable command. Rendered once per command

file into the per-tool envelope by config-export command mode. Expresses

cross-session persistence in tool-neutral prose — it issues NO tool-specific

call, so it passes the export STRIP guard verbatim.

This command persists its work across sessions through engram, registered as an MCP server in this tool. Use this tool's own engram memory tools to honor the contract below — do not assume any other persistence layer.

Recall before acting

When the first input is a continuation keyword ("listo", "dale", "seguimos", "ready", "where did we leave off", "qué sigue"), DO NOT start fresh. First search engram for prior work on this change — by the change name and by recent topic keys — then summarize what you found and continue from there. Skipping the search and asking "what can I help with?" means you ignored existing context.

Validate after saving

After any save, verify it actually persisted: search engram back for the key or a unique phrase you just wrote. A tool response of "saved" is NOT proof the row landed. If the verifying search does not return the row, retry once; if it still fails, tell the user the save failed — never report "saved" on the tool response alone.

Summarize at close

Before ending a session, write a session summary to engram (goal, what was done, decisions, next steps, relevant files) so the next session can recover context. Recovery is never automatic — every session must search engram to find prior state.

When engram is unreachable

If engram is not installed or not on PATH, memory operations cannot persist. When that happens, emit a visible warning to the user that engram was not found (not installed / not on PATH) and that this session's work will NOT survive. DO NOT report memory as saved, and DO NOT proceed silently as if persistence had occurred. See the install prerequisite in the onboarding docs to enable engram.

Skill Logic: feature-domain-expert

Authoritative guide for authoring and consuming feature knowledge files in

ai-context/features/. Reference skill — tool-neutral logic, no harness-specific

wiring.

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:

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-manage. 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-manage and leave sections

empty until knowledge is acquired.

---

Pattern 3: What belongs in each of the six sections

Structure is defined elsewhere. The canonical six-section structure — headings,

order, fill-in prompts, and [auto-updated] markers — lives in

skills/_templates/feature/_template.md. It is the single structural source of

truth, consumed by the codebase-teach and feature-define skills. Do NOT re-describe

the structure here. This pattern covers only the semantics: what kind of

knowledge belongs in each section and why — the judgment the template's fill-in

prompts cannot encode.

1. Domain Overview — purpose and scope of the bounded context, not implementation detail. Answer: what is this context responsible for, and who owns it?

2. Business Rules and Invariants — constraints that stay true even if the implementation were rewritten from scratch. If it depends on a specific code path, it is not an invariant. E.g. "A refund cannot exceed the original payment amount."

3. Data Model Summary — orient the reader to the most important entities and their relationships and critical constraints. Not a full schema — the key entities only.

4. Integration Points — every external system this context depends on or exposes to, including async contracts (events, queues) and third-party dependencies, with direction.

5. Decision Log — significant design/implementation decisions, each with rationale and what it constrains going forward. Entries are historical record: NEVER deleted.

6. Known Gotchas — operational hazards, historical defects, non-obvious constraints; the things that caused bugs or tripped up previous contributors. Kept even after the bug is fixed.

---

Pattern 4: Domain slug matching heuristic (used by sdd-propose Step 0 and sdd-spec Step 0)

When an SDD phase runs for <change-name>, it determines which feature files to preload using this algorithm:

Input:  change-name (kebab-case string)
Output: list of matching ai-context/features/<domain>.md paths (may be empty)

Algorithm:
  1. If ai-context/features/ does not exist → return [] (skip silently)
  2. List all .md files in ai-context/features/
  3. Exclude any file whose name starts with underscore (e.g. _template.md)
  4. Extract stems: split change-name on "-", discard single-char stems
  5. For each remaining file f:
       domain = filename stem of f (without .md extension)
       if domain appears in change-name
         OR any stem from step 4 appears in domain:
         add f to matches
  6. Return all matches (may be multiple files)
  7. If matches is empty → skip preload silently (no error, no warning)

Examples:

Key behaviors:

• _template.md is ALWAYS excluded — it is never a preload candidate.
• The match is bidirectional: domain-in-change-name OR change-stem-in-domain.
• Multiple files may match — all are loaded as enrichment context.
• A non-match is NOT an error: the phase proceeds normally without domain context.

---

Pattern 5: Updating a feature file via /memory-manage

Feature files follow an append-only update discipline. When /memory-manage runs after a session that involved a domain with an existing feature file:

1. Business Rules and Invariants: append newly discovered rules as new list items. Never remove or reword existing rules unless they are factually wrong (in which case add a correction note below the original rule instead of deleting it). 2. Decision Log: append a new dated entry for any domain decision made during the session. Entries are never deleted or reordered. 3. Known Gotchas: append new gotchas discovered during the session. Never remove a gotcha — even if the underlying bug was fixed, a note about the former behavior is useful history. 4. Other sections: update Data Model Summary and Integration Points if new entities or integrations were introduced. Domain Overview may be updated if the scope of the domain changed significantly.

/memory-manage MUST NOT create new feature files — it only updates existing ones. New feature files are created manually or scaffolded by memory-manage.

Respect [auto-updated] section boundaries if present (same convention as in other ai-context files).

---

Pattern 6: Worked example — the sdd-meta-system domain

The canonical worked example for this skill is ai-context/features/sdd-meta-system.md in the agent-config repository. It demonstrates all six sections with realistic content for the SDD meta-system bounded context.

Below is an abbreviated illustration of the pattern each section should follow:

Domain Overview (2–4 sentences of purpose and scope):

"The SDD meta-system is the agent configuration and skill orchestration framework...

It provides two primary capabilities: a library of reusable skills and an SDD phase pipeline...

The system is self-hosting: changes to its own skills must follow the same SDD cycle."

Business Rules and Invariants (declarative always-true statements):

- Every skill modification MUST go through the SDD planning cycle (at minimum /sdd-propose) before /sdd-apply.
- sync.sh MUST only move memory/ from the deployed config home to the repo.
- Developers MUST NOT edit files in the deployed config home directly.

Data Model Summary (table of key entities with constraints):

| Entity        | Key Fields                         | Constraints                               |
|---------------|------------------------------------|--------------------------------------------|
| Skill         | directory name, SKILL.md, format   | format must be procedural|reference|anti-pattern |
| SDD Change    | proposal, design, tasks             | stored as sdd/<name>/* artifacts |

Integration Points (table of systems with direction and contract):

| System      | Direction | Contract                                              |
|-------------|-----------|-------------------------------------------------------|
| install.sh  | outbound  | Deploys repo to the config home — run after any config change |
| sync.sh     | inbound   | Copies the deployed memory/ to repo — memory only         |

Decision Log (chronological, with rationale and impact):

### 2026-03-03 — Add ai-context/features/ as Tier 1 domain knowledge layer
Decision: Introduce ai-context/features/<domain>.md as a permanent sub-layer...
Rationale: SDD phase skills lack access to stable business context between cycles...
Impact: sdd-propose and sdd-spec gain a non-blocking Step 0 that preloads matching feature files.

Known Gotchas (operational hazards and non-obvious behaviors):

- sync.sh does NOT deploy skills. Running it after a skill edit does nothing — run install.sh.
- Direct edits to the deployed config home are silently lost on the next install.sh run.

For the full worked example, read ai-context/features/sdd-meta-system.md.

---

Rules

• A feature file MUST follow the canonical six-section structure defined in

skills/_templates/feature/_template.md. Each project should NOT keep a local _template.md copy — the canonical template lives in the global agent-config and is consumed by /feature-define at scaffolding time. Sections must appear in this exact order: Domain Overview, Business Rules and Invariants, Data Model Summary, Integration Points, Decision Log, Known Gotchas.

• Feature files MUST be named <domain-slug>.md where the slug is lowercase and hyphen-separated.

No subdirectories are allowed inside ai-context/features/.

• _template.md and any file with a leading underscore are excluded from the domain preload

heuristic. They MUST NOT be loaded by SDD phases.

• Feature files encode permanent domain knowledge — they are updated but NEVER deleted or archived.

Do not confuse them with SDD spec artifacts (stored as sdd/<change>/spec), which are created per change and eventually archived.

• The domain preload step in sdd-propose and sdd-spec is non-blocking. A missing

ai-context/features/ directory or a non-matching slug MUST NOT produce a warning or failure. The phase always proceeds normally.

• /memory-manage appends to feature files — it MUST NOT overwrite or delete existing content.

/memory-manage MUST NOT create new feature files; only scaffold them via memory-manage or manual authoring.

• codebase-teach does NOT write to ai-context/features/. Feature files require domain expert

judgment; they must not be auto-overwritten by a structural scan.

• The feature_docs: block in project config is reserved for V2 audit integration. Do not

activate it in V1.