evanflow-glossary

Name: evanflow-glossary
Author: evanklem

419stars18forks

How to install evanflow-glossary?

evanklem/evanflow/evanflow-glossary

$npx -y skills add evanklem/evanflow --skill evanflow-glossary

Installs into the current project.

Summary

Extract canonical domain terms into CONTEXT.md. Flag ambiguities (same word, different meanings) and synonyms (different words, same meaning). Re-invoking updates the file in place. Use when authoring or updating CONTEXT.md, or when a new domain term emerges in conversation.

Files · 1

View on GitHub

SKILL.md

1	# EvanFlow: Ubiquitous Language
2
3
4	## Vocabulary
5
6	See `evanflow` meta-skill.
7
8	## When to Use
9
10	- Authoring `CONTEXT.md` for the first time (Phase B of EvanFlow rollout)
11	- A new domain term emerged in conversation and should be added
12	- Auditing existing terminology for ambiguity (same word, multiple meanings) or synonyms (different words, same meaning)
13	- Before any architectural conversation that depends on shared language
14
15	## The Flow
16
17	### 1. Read Current State
18
19	- If `CONTEXT.md` exists: read it. Identify clusters and gaps.
20	- Read recent code in the relevant area: router file, service file, schema, page. Names in code are the de facto terminology.
21	- Read recent ADRs in `docs/adr/` for terms decided there.
22
23	### 2. Extract Terms
24
25	Walk the conversation + relevant code. Pull out:
26
27	- Nouns — entities and value objects in your domain
28	- Verbs — domain operations (e.g., negotiate, queue, withdraw, settle, escalate)
29	- Status enums — explicit lifecycle states (e.g., `OrderStatus`, `MessageStatus`)
30	- Relationships — cardinalities between entities (one-to-many, many-to-many)
31
32	### 3. Flag Conflicts
33
34	Two questions to ask the user for each conflict:
35
36	- Ambiguity: "The word `X` is used for both A and B. Which canonical meaning, and what should the other one be renamed to?"
37	- Synonyms: "The codebase uses both `User` and `Account` for the same concept. Which is canonical? The other becomes a deprecated alias."
38
39	Propose recommended answers. Don't just dump the conflicts on the user.
40
41	### 4. Write CONTEXT.md
42
43	Default location: `/CONTEXT.md` at repo root. (Mattpocock convention.)
44
45	Format:
46
47	```markdown
48	# <Project> Domain Language
49
50	## <Cluster Name> (e.g., "Identity & Accounts")
51
52	\| Term \| Definition (one sentence) \| Aliases to avoid \|
53	\|---\|---\|---\|
54	\| User \| Canonical noun for an authenticated account. \| Account (legacy), Customer (billing-layer only) \|
55	\| Category \| A primary classification used for matching/filtering. \| Type, Tag, Vertical \|
56
57	## <Next Cluster>
58
59	...
60
61	## Relationships
62
63	- EntityA → EntityB: many-to-many via a join table.
64	- EntityA → EntityC: one-to-many; EntityCs are managed by an automated process.
65	```
66
67	### 5. Re-invoke Behavior
68
69	If `CONTEXT.md` already exists:
70
71	- Read it
72	- Add new terms in their existing cluster (or create a new cluster)
73	- Update evolved definitions
74	- Refresh the example dialogue if present
75	- Don't duplicate; merge
76
77	## Hard Rules
78
79	- One sentence per definition. If you need a paragraph, the term is too vague — split it.
80	- Domain terms only. Skip generic programming concepts (function, class, etc.).
81	- Be prescriptive. Pick canonical synonyms; don't list every variant as equally valid.
82	- Cardinality in bold. "User has many Orders."
83	- Never auto-commit. Append CONTEXT.md changes to a stage; ask before commit.
84
85	## Hand-offs
86
87	- New ADR needed (decision behind a term) → write under `docs/adr/`
88	- Terms reveal architectural friction → `evanflow-improve-architecture`

People who liked this also viewed

6 picks

Type

evanflow-glossary

419stars18forks

View on GitHub

How to install evanflow-glossary?

evanklem/evanflow/evanflow-glossary

$npx -y skills add evanklem/evanflow --skill evanflow-glossary

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# EvanFlow: Ubiquitous Language
2
3
4	## Vocabulary
5
6	See `evanflow` meta-skill.
7
8	## When to Use
9
10	- Authoring `CONTEXT.md` for the first time (Phase B of EvanFlow rollout)
11	- A new domain term emerged in conversation and should be added
12	- Auditing existing terminology for ambiguity (same word, multiple meanings) or synonyms (different words, same meaning)
13	- Before any architectural conversation that depends on shared language
14
15	## The Flow
16
17	### 1. Read Current State
18
19	- If `CONTEXT.md` exists: read it. Identify clusters and gaps.
20	- Read recent code in the relevant area: router file, service file, schema, page. Names in code are the de facto terminology.
21	- Read recent ADRs in `docs/adr/` for terms decided there.
22
23	### 2. Extract Terms
24
25	Walk the conversation + relevant code. Pull out:
26
27	- Nouns — entities and value objects in your domain
28	- Verbs — domain operations (e.g., negotiate, queue, withdraw, settle, escalate)
29	- Status enums — explicit lifecycle states (e.g., `OrderStatus`, `MessageStatus`)
30	- Relationships — cardinalities between entities (one-to-many, many-to-many)
31
32	### 3. Flag Conflicts
33
34	Two questions to ask the user for each conflict:
35
36	- Ambiguity: "The word `X` is used for both A and B. Which canonical meaning, and what should the other one be renamed to?"
37	- Synonyms: "The codebase uses both `User` and `Account` for the same concept. Which is canonical? The other becomes a deprecated alias."
38
39	Propose recommended answers. Don't just dump the conflicts on the user.
40
41	### 4. Write CONTEXT.md
42
43	Default location: `/CONTEXT.md` at repo root. (Mattpocock convention.)
44
45	Format:
46
47	```markdown
48	# <Project> Domain Language
49
50	## <Cluster Name> (e.g., "Identity & Accounts")
51
52	\| Term \| Definition (one sentence) \| Aliases to avoid \|
53	\|---\|---\|---\|
54	\| User \| Canonical noun for an authenticated account. \| Account (legacy), Customer (billing-layer only) \|
55	\| Category \| A primary classification used for matching/filtering. \| Type, Tag, Vertical \|
56
57	## <Next Cluster>
58
59	...
60
61	## Relationships
62
63	- EntityA → EntityB: many-to-many via a join table.
64	- EntityA → EntityC: one-to-many; EntityCs are managed by an automated process.
65	```
66
67	### 5. Re-invoke Behavior
68
69	If `CONTEXT.md` already exists:
70
71	- Read it
72	- Add new terms in their existing cluster (or create a new cluster)
73	- Update evolved definitions
74	- Refresh the example dialogue if present
75	- Don't duplicate; merge
76
77	## Hard Rules
78
79	- One sentence per definition. If you need a paragraph, the term is too vague — split it.
80	- Domain terms only. Skip generic programming concepts (function, class, etc.).
81	- Be prescriptive. Pick canonical synonyms; don't list every variant as equally valid.
82	- Cardinality in bold. "User has many Orders."
83	- Never auto-commit. Append CONTEXT.md changes to a stage; ask before commit.
84
85	## Hand-offs
86
87	- New ADR needed (decision behind a term) → write under `docs/adr/`
88	- Terms reveal architectural friction → `evanflow-improve-architecture`

People who liked this also viewed

6 picks

Type