Skip to content

feat: /glossary skill — Evans DDD ubiquitous language + bounded contexts#1232

Draft
amargandhi wants to merge 1 commit intogarrytan:mainfrom
amargandhi:pr/glossary-skill
Draft

feat: /glossary skill — Evans DDD ubiquitous language + bounded contexts#1232
amargandhi wants to merge 1 commit intogarrytan:mainfrom
amargandhi:pr/glossary-skill

Conversation

@amargandhi
Copy link
Copy Markdown

Summary

Adds /glossary — a pure-documentation skill grounded in Evans 2003 Domain-Driven Design, Ch. 2 (ubiquitous language) and Ch. 14 (bounded contexts + 9 relationship types). Builds an ubiquitous language doc with bounded contexts and a context map. The highest-value output is naming language seams — terms that mean different things in different contexts.

Why a new skill

Most codebases accumulate vocabulary mismatch over time. Same word, different meanings in different modules ("subscription" = billing artifact here, push-notification target there). Same concept, different names ("user" / "account" / "profile" / "member" all referring to one entity). Evans named this 22 years ago; gstack now systematically catches it.

Hard gate

Documentation only. Does NOT rename anything, refactor anything, or propose architecture changes. Renames motivated by glossary findings are a separate conversation. Documented prominently in the template.

Output structure

  • Section 1 — Bounded contexts (one per coherent subsystem)
  • Section 2 — Context map with 9 Evans relationship types annotated: Shared Kernel, Customer/Supplier, Conformist, Anticorruption Layer, Open Host Service, Published Language, Separate Ways, Partnership, Big Ball of Mud
  • Section 3 — Ubiquitous language (terms with definition + bounded context owner)
  • Section 4 — Language seams (the highest-value output: terms that collide across contexts)

What this PR adds

  1. `glossary/SKILL.md.tmpl` (284 lines) — defines the 4-section walk, HARD GATE prose, ranking heuristics, and gotcha guidance ("name the seams", "don't refactor", "accept partial").
  2. `scripts/resolvers/preamble/generate-routing-injection.ts` — adds one bullet so Claude/Codex auto-route phrases like "build a domain glossary", "document ubiquitous language", "find naming inconsistencies" to /glossary.
  3. Generated SKILL.md across all 10 hosts — ~11K tokens per generated skill, well under the 40K ceiling.

Test plan

  • `bun test test/skill-validation.test.ts test/gen-skill-docs.test.ts` — 689/689 pass
  • `bun run gen:skill-docs --host all` — clean regen, no warnings, no token-ceiling alerts
  • Built against upstream/main at v1.15.0.0

Notes for review

  • This pairs naturally with /challenge (PR feat: /challenge skill — Polya 4-stage plan stress-test #1231) and is part of a 7-branch canonical-literature series on my fork. /glossary is the most stand-alone of the seven — pure new skill, zero dependencies on other skills.
  • Voice and style follow gstack conventions: short sentences, named sources (Evans 2003 cited inline), no AI vocabulary, no em dashes in new prose.
  • One concrete user benefit: running `/glossary` on a 50K-line codebase catches naming drift that `/review` and `/plan-eng-review` are not built to surface.

Pure-documentation skill grounded in Evans 2003 *Domain-Driven Design*,
Ch. 2 (ubiquitous language) and Ch. 14 (bounded contexts + 9 relationship
types). Builds an ubiquitous language doc with bounded contexts and the
context map. Surfaces "language seams" — terms that mean different things
in different contexts.

**Why a new skill:** Most codebases accumulate a vocabulary mismatch over
time. The same word means different things in different modules
("subscription" = billing artifact in one context, push-notification
target in another), and the same concept gets named differently
("user" / "account" / "profile" / "member" all referring to one entity).
Evans named this; gstack now systematically catches it.

**Hard gate:** Documentation only. Does NOT rename anything, refactor
anything, or propose architecture changes. Renames motivated by glossary
findings are a separate conversation.

**Output structure:**
- Section 1 — Bounded contexts (one per coherent subsystem)
- Section 2 — Context map with 9 Evans relationship types annotated:
  Shared Kernel, Customer/Supplier, Conformist, Anticorruption Layer,
  Open Host Service, Published Language, Separate Ways, Partnership,
  Big Ball of Mud
- Section 3 — Ubiquitous language (terms with definition + bounded
  context owner)
- Section 4 — Language seams (the highest-value output: terms that
  collide across contexts)

What this PR adds:

1. `glossary/SKILL.md.tmpl` (284 lines) — defines the 4-section walk,
   HARD GATE prose, ranking heuristics, and gotcha guidance ("name the
   seams", "don't refactor", "accept partial").
2. `scripts/resolvers/preamble/generate-routing-injection.ts` — adds one
   bullet so Claude/Codex auto-route phrases like "build a domain
   glossary", "document ubiquitous language", "find naming
   inconsistencies" to /glossary.
3. Generated SKILL.md across all 10 hosts — ~11K tokens per skill,
   well under the 40K ceiling.

Tests: 689/689 pass. Built and tested against upstream/main at v1.15.0.0.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant