Ubiquitous Language

---
layer: peripheral
name: ubiquitous-language
description: "Usar cuando se necesita extraer o consolidar el glosario de términos de dominio de un proyecto. Trigger: usuario dice 'extrae glosario', 'ubiquitous language', '/glossary', o hay >5 términos repetidos sin CONTEXT.md."
metadata:
  # --- metadata.savia.* (SE-333) ---
  savia.attribution: "Clean-room re-implementation of mattpocock/skills/ubiquitous-language + domain-model (MIT, 26.4k*). Prose and process are original."
  savia.maturity: stable
  savia.category: ddd
  savia.context: project
  savia.context_cost: low
  savia.priority: medium
  savia.tags: "ddd, glossary, domain, context, ubiquitous-language"
---

# Authoritative Paths

- Glossary output: `projects/<project>/CONTEXT.md`
- Extractor script: `scripts/extract-domain-entities.py`
- Rule doc: `docs/rules/domain/ubiquitous-language.md`
- Related: SE-082 (`docs/rules/domain/architectural-vocabulary.md`) — architectural terms (universal); this skill — domain terms (per-project).

# Ubiquitous Language Extractor

Extracts domain terms from conversations or text sources and consolidates them
into a per-project `CONTEXT.md` glossary. Based on DDD "ubiquitous language"
pattern (Eric Evans). SE-086.

## Triggers

- User says "extrae glosario", "ubiquitous language", "glossary", "/glossary"
- Agent detects >5 domain terms repeated without a `CONTEXT.md` present
- User asks "what does X mean in this project?"

## Process (5 steps)

### Step 1 — Identify source
Ask user: conversation (last N turns), a specific file path, or
`output/.memory-store.jsonl`. Default: last conversation turns.

### Step 2 — Extract candidates
Scan source for domain terms:
- Capitalized multi-word concepts used consistently ("Skill Maturity", "Era", "Slice")
- Project-specific jargon repeated ≥2 times ("sprint", "AC", "PBI", "hook")
- Abbreviations with consistent meaning ("SDD", "CRC", "ADO")
- Exclude: pure infrastructure terms (function names, file paths, commands)

### Step 3 — Infer definitions
For each candidate: derive a 1-sentence definition from usage context.
Mark as `[REVIEW]` when uncertain.

### Step 4 — Validate with user
Show a table: `term | proposed definition | confidence`. Ask:
- Are any definitions wrong?
- Are any important terms missing?
- Confirm target: `projects/<project>/CONTEXT.md` (or custom path)?

### Step 5 — Write / merge
- If `CONTEXT.md` exists: merge new terms, flag conflicts as `[INCONSISTENT]`.
- If absent: create with standard header + glossary table.
- Never overwrite existing definitions without explicit confirmation.

## CONTEXT.md format

```markdown
# Domain Glossary — <Project>

> Auto-generated by ubiquitous-language skill (SE-086). Review all [REVIEW] entries.
> Last updated: YYYY-MM-DD

| Term | Definition | Status |
|------|------------|--------|
| Era  | A named development cycle (~2 weeks) grouping related specs. | stable |
| Slice | A vertical implementation unit within a spec. | stable |
| AC   | Acceptance Criterion — testable condition on a spec. | [REVIEW] |
```

Status values: `stable`, `[REVIEW]`, `[INCONSISTENT]`.

## Script mode (Slice 2)

For automated extraction from memory-store:

```bash
python3 scripts/extract-domain-entities.py --project pm-workspace
python3 scripts/extract-domain-entities.py --project pm-workspace --auto-update
```

Output: `output/domain-entity-report-<project>-<date>.md`

## Constraints

- Never claim a definition is authoritative — always surface for human review.
- Never delete existing terms from CONTEXT.md.
- Scope: per-project terms only — universal architectural vocabulary is SE-082.