evanflow-glossary

EvanFlow: Ubiquitous Language

Vocabulary

See evanflow meta-skill.

When to Use

• Authoring CONTEXT.md for the first time (Phase B of EvanFlow rollout)
• A new domain term emerged in conversation and should be added
• Auditing existing terminology for ambiguity (same word, multiple meanings) or synonyms (different words, same meaning)
• Before any architectural conversation that depends on shared language

The Flow

1. Read Current State

• If CONTEXT.md exists: read it. Identify clusters and gaps.
• Read recent code in the relevant area: router file, service file, schema, page. Names in code are the de facto terminology.
• Read recent ADRs in docs/adr/ for terms decided there.

2. Extract Terms

Walk the conversation + relevant code. Pull out:

• Nouns — entities and value objects in your domain
• Verbs — domain operations (e.g., negotiate, queue, withdraw, settle, escalate)
• Status enums — explicit lifecycle states (e.g., OrderStatus, MessageStatus)
• Relationships — cardinalities between entities (one-to-many, many-to-many)

3. Flag Conflicts

Two questions to ask the user for each conflict:

• Ambiguity: "The word X is used for both A and B. Which canonical meaning, and what should the other one be renamed to?"
• Synonyms: "The codebase uses both User and Account for the same concept. Which is canonical? The other becomes a deprecated alias."

Propose recommended answers. Don't just dump the conflicts on the user.

4. Write CONTEXT.md

Default location: /CONTEXT.md at repo root. (Mattpocock convention.)

Format:

# <Project> Domain Language

## <Cluster Name> (e.g., "Identity & Accounts")

| Term | Definition (one sentence) | Aliases to avoid |
|---|---|---|
| **User** | Canonical noun for an authenticated account. | Account (legacy), Customer (billing-layer only) |
| **Category** | A primary classification used for matching/filtering. | Type, Tag, Vertical |

## <Next Cluster>

...

## Relationships

- **EntityA** → **EntityB**: many-to-many via a join table.
- **EntityA** → **EntityC**: one-to-many; EntityCs are managed by an automated process.

5. Re-invoke Behavior

If CONTEXT.md already exists:

• Read it
• Add new terms in their existing cluster (or create a new cluster)
• Update evolved definitions
• Refresh the example dialogue if present
• Don't duplicate; merge

Hard Rules

• One sentence per definition. If you need a paragraph, the term is too vague — split it.
• Domain terms only. Skip generic programming concepts (function, class, etc.).
• Be prescriptive. Pick canonical synonyms; don't list every variant as equally valid.
• Cardinality in bold. "User has many Orders."
• Never auto-commit. Append CONTEXT.md changes to a stage; ask before commit.

Hand-offs

• New ADR needed (decision behind a term) → write under docs/adr/
• Terms reveal architectural friction → evanflow-improve-architecture