domain-context

What this skill does

# Progressive Domain Crystallization (PDC) Skill

## What This Skill Does

This skill enables any AI assistant to build and use a **living domain knowledge base** for any business
application — accumulated incrementally across sessions through a human-AI collaborative protocol.

The AI never "knows" the domain by default. But with this skill, it can:
- Read a structured `.tasks/domain.md` file at the start of every session
- Use internal terminology and entity names exactly as the business defines them
- Flag gaps in domain understanding inline during work
- Propose structured additions to the domain file for human review
- Never corrupt the knowledge base — all updates are proposed, not auto-applied
- Manage domain knowledge growth through progressive disclosure — loading only what's relevant to the current session

---

## Core Protocol

### At Session Start

1. **Look for .tasks/domain.md** in the project root
2. If found → check the file structure:
   - **Single file** (under ~200 lines): Read it completely before doing any work.
   - **Index + detail files** (split structure): Read the root .tasks/domain.md index (Tier 1 — core context). Then determine which Tier 2 detail files are relevant to the current task and load only those. See § Progressive Disclosure.
3. If not found → offer to initialize one using the template at `.tasks/domain.md`
4. Confirm to the user: "I've loaded the domain context for [Project Name]. I'm familiar with [N] entities and [N] flows." If in split mode, also note: "I've loaded the core context. I'll pull in detail files as needed for what we're working on."

### During Work

- Use entity names, terminology, and abbreviations **exactly as defined** in .tasks/domain.md
- When encountering an undefined term or entity, mark it inline: `[UNKNOWN: <term>]`
- When a relationship between entities is unclear, mark it: `[RELATIONSHIP UNCLEAR: <entity-a> → <entity-b>]`
- When a business rule seems to be implied but isn't documented: `[RULE INFERRED: <description>]`
- Do not invent domain facts — use only what is documented or what the user confirms in session
- When working on a specific entity or flow, load its Tier 2 detail file if one exists and hasn't been loaded yet

### At Session End

Always generate a `## 📋 Proposed Domain Updates` section at the bottom of your final response.

Format it as:

```markdown
## 📋 Proposed Domain Updates

> Review these and copy any confirmed items into your .tasks/domain.md

### New Entities Discovered
- **[EntityName]**: [Definition as understood from this session]
  - Attributes: [list]
  - Related to: [other entities]

### Terminology Clarified
- `[term]` → [plain definition]

### Relationships Identified
- [Entity A] → [verb] → [Entity B]: [description]

### Business Rules Observed
- [Rule description]

### Open Questions
- [ ] [Question about something ambiguous or unresolved]

### Suggested .tasks/domain.md Sections to Add/Update
- [ ] [specific section or entry to update]
```

The human reviews this, edits as needed, and manually updates .tasks/domain.md. This keeps the human as domain authority.

---

## Progressive Disclosure

Domain knowledge files grow over time. A single .tasks/domain.md that works well at 80 lines becomes unwieldy at 400. Progressive disclosure keeps the AI focused on what's relevant to the current session without losing access to the full knowledge base.

### Three Tiers of Domain Knowledge

| Tier | What It Contains | When It's Loaded | Typical Size |
|------|-----------------|-------------------|-------------|
| **Tier 1 — Core** | Project overview, terminology glossary, entity names (one-liners only), business rules table, user roles table | **Always**, at session start | 80–120 lines |
| **Tier 2 — Working Context** | Full entity descriptions (lifecycle, notes, edge cases), full flow step-by-steps, relationship map, integration points | **On demand**, when the session touches that entity or flow | 30–80 lines per file |
| **Tier 3 — Archive** | Changelog, resolved open questions, data migration notes, vendor-specific details | **On explicit request**, or when reviewing project history | Variable |

### What Goes in Each Tier

**Tier 1 — Core (root .tasks/domain.md, always loaded):**
- `## Project Overview` — what it is, who uses it, business goal (5 lines)
- `## Domain Boundaries` — what's in scope, what's supporting, what's explicitly excluded. Prevents overbuilding.
- `## Terminology Glossary` — the shorthand table
- `## Entity Registry` — **names and one-liner descriptions only** (not full attribute lists, not lifecycle details, not notes). Think of this as a table of contents for the entities.
- `## State Models` — named enumerations and valid state transitions for entities with statuses or lifecycle stages. The AI must treat these as the only valid values.
- `## Business Rules` — the hard rules table (BR-001, BR-002, etc.). These are ground truth the AI must always know.
- `## User Roles` — the roles table
- `## Stakeholder Map` — named people, their relationship to the system, their key concerns, and when to involve them. Critical for adoption and buy-in.
- `## Open Questions` — current unresolved items
- `## Detail Files` — index of Tier 2 files with one-line summaries (see file layout below)

**Tier 2 — Working Context (separate files, loaded by task):**
- Full entity specs — attributes, lifecycle, relationships, notes, edge cases (one file per major entity)
- Full flow descriptions — step-by-step process walkthroughs (one file per flow)
- Relationship map — the full entity-to-entity table
- Integration points — external system details

**Tier 3 — Archive (separate files, loaded on request):**
- Changelog — session-by-session history of what was learned
- Resolved questions — historical record of closed open questions
- Data migration notes — vendor catalog details, import procedures
- Vendor-specific details — price sheet structures, portal access notes

### When to Split: The ~200 Line Rule

A single .tasks/domain.md works well for early-stage projects. The trigger to split is simple:

**When .tasks/domain.md exceeds ~200 lines, propose the split.**

Say to the user: "The domain file is getting substantial — [N] lines with [N] entities and [N] flows. Want me to split it into an index file with detail files? This keeps sessions focused on what's relevant without losing anything."

If the user agrees, restructure into the tiered file layout (see below). If they prefer a single file, respect that — it's a preference, not a hard requirement.

### How the AI Uses Tiers at Session Start

```
1. Read root .tasks/domain.md (Tier 1 — always)
      ↓
2. Understand the current task
      ↓
3. Determine which entities/flows are relevant
      ↓
4. Load only those Tier 2 files
      ↓
5. Work — loading additional Tier 2 files if the task expands
      ↓
6. Propose updates — specifying which file each update belongs to
```

Example: User says "I need to update the PM renewal flow." The AI:
1. Reads root .tasks/domain.md (core context — knows all entity names, all business rules)
2. Loads `docs/domain/flows/pm-renewal.md` (the relevant flow)
3. Loads `docs/domain/entities/pm-renewal.md` (the relevant entity)
4. Does NOT load `docs/domain/flows/lead-distribution.md` or `docs/domain/entities/customer.md` — not relevant to this task.

### Proposing Updates in Split Mode

When the domain is split across files, the Proposed Domain Updates section should specify **which file** each update belongs to:

```markdown
## 📋 Proposed Domain Updates

### Update: `.tasks/domain.md` (Tier 1 — core)
- Add to Business Rules: BR-013 — [rule description]

### Update: `docs/domain/entities/pm-renewal.md` (Tier 2)
- Add attribute: `priceAdjustmentPercent` — annual price increase applied on renewal

### New File: `docs/domain/flows/engineering-review.md` (Tier 2)
- [Full flow description to create]

### Update: `docs/domain/archive/changelog.md` (Tier 3)
- [Session summary entry]