vm-ubiquitous-language-extractor

# VM Ubiquitous Language Extractor

## Overview

Scans a conversation, set of requirement documents, or codebase to extract domain-relevant terms. Produces a canonical glossary with opinionated term choices, flags ambiguities, and writes to `UBIQUITOUS_LANGUAGE.md` in the working directory. Supports incremental re-runs: re-invoking merges new terms without overwriting prior definitions.

## When to Use

- When team members use different words for the same concept
- Before writing user stories or requirement documents to align on terminology
- When onboarding a new team member onto a complex domain
- When a requirements document uses ambiguous or overloaded terms
- When building a bounded-context model (DDD) and a glossary is required
- When feeding requirements into the Requirement Gap Analyzer or Change Impact Analysis Agent

## When NOT to Use

- Generic programming terms (class, endpoint, function) — unless they carry domain-specific meaning
- Infrastructure or operational terms with no business context
- As a replacement for domain modelling; this skill extracts language, not structure

## Inputs

Accept any of the following as sources:

- The current conversation text
- An attached or referenced requirements document, PRD, or specification
- Codebase — scan class names, method names, field names, and comments for domain terms
- A Confluence export or architecture document

Sources are processed in priority order: codebase > requirements documents > conversation.

## Method

### Step 1: Scan for Domain Terms

Scan all input sources for:
- Domain-relevant **nouns** (entities, events, concepts, roles, states)
- Domain-relevant **verbs** (actions, transitions, operations)
- Any term used inconsistently across sources

Skip: generic programming terms, framework names, infrastructure terms — unless they carry specific domain meaning.

### Step 2: Identify Problems

For each candidate term, check:
- **Synonyms**: Different words used for the same concept (pick one, alias the rest)
- **Ambiguity**: Same word used for different concepts (must split into distinct terms)
- **Overloaded terms**: A term that means different things in different contexts (flag the contexts)
- **Undefined jargon**: Terms used without definition (flag as `needs_definition`)

### Step 3: Propose Canonical Glossary

- **Be opinionated.** When multiple words exist for the same concept, pick the best one, list the others as "aliases to avoid."
- **Flag conflicts explicitly.** Any term used ambiguously MUST appear in the "Flagged ambiguities" section.
- **Keep definitions tight.** One sentence maximum. Define what it IS, not what it does.
- **Show relationships.** Use bold term names and express cardinality where obvious.
- **Group terms** by natural clusters (subdomain, lifecycle stage, actor). If all terms belong to one cohesive domain, one table is fine.
- **Write an example dialogue.** 3–5 exchanges between a developer and a domain expert demonstrating how the terms interac