ubiquitous-language

Files (1)

• SKILL.md

SKILL.md (first lines)

# Ubiquitous Language (Per Bounded Context)

## When to use this skill

Use this skill when a single named bounded context (from
`docs/adr/0005-bounded-contexts.md`) needs a crisp glossary — typically
right after `zoom-out` reveals two callers using the same word for
different concepts, or as part of a domain-modelling pass before refactor.
The trigger is "we need a canonical glossary for context X". This skill
REFUSES to run without an explicit context name; there is no repo-wide
glossary mode.

## Bounded Context Required

This skill is hard-coupled to the EVOKORE-MCP context map in
[`docs/adr/0005-bounded-contexts.md`](../../../docs/adr/0005-bounded-contexts.md).
The eight bounded contexts are:

1. **Skill Registry & Discovery** — `src/SkillManager.ts`,
   `src/RegistryManager.ts`, `src/ToolCatalogIndex.ts`,
   `src/ToolCatalogPagination.ts`, `src/ProfileResolver.ts`,
   `src/rerank/successRerank.ts`.
2. **Proxy & Routing** — `src/ProxyManager.ts`,
   `src/utils/resolveCommandForPlatform.ts`, `src/httpUtils.ts`.
3. **Auth & Security** — `src/auth/OAuthProvider.ts`,
   `src/SecurityManager.ts`, `src/ComplianceChecker.ts`,
   `src/ContainerSandbox.ts`.
4. **Session & Continuity** — `src/SessionIsolation.ts`,
   `src/SessionManifest.ts`, `src/SessionManifest.schema.ts`,
   `src/SessionStore.ts`, `src/stores/MemorySessionStore.ts`,
   `src/stores/FileSessionStore.ts`, `src/stores/RedisSessionStore.ts`,
   `src/HttpServer.ts`.
5. **Orchestration & Fleet** — `src/OrchestrationRuntime.ts`,
   `src/FleetManager.ts`, `src/ClaimsManager.ts`,
   `src/WorkerManager.ts`, `src/WorkerScheduler.ts`,
   `src/TrustLedger.ts`.
6. **Audit & Webhooks** — `src/AuditLog.ts`, `src/AuditExporter.ts`,
   `src/WebhookManager.ts`, `src/PluginManager.ts`.
7. **Telemetry & Analytics** — `src/TelemetryManager.ts`,
   `src/TelemetryExporter.ts`, `src/TelemetryIndex.ts`,
   `src/SessionAnalyticsManager.ts`, `src/NavigationAnchorManager.ts`.
8. **Memory & Knowledge** — `src/MemoryManager.ts`.

The voice subsystem is NOT a bounded context (per ADR-0005's
"Out-of-context" section); this skill rejects `--context voice`.

The context name (slug form, kebab-case) MUST be passed as `--context
<slug>` (or equivalent argv) when invoking. Accepted slugs are:
`skill-registry-and-discovery`, `proxy-and-routing`,
`auth-and-security`, `session-and-continuity`,
`orchestration-and-fleet`, `audit-and-webhooks`,
`telemetry-and-analytics`, `memory-and-knowledge`.

If no `--context` is provided, this skill MUST refuse to run, emit an
error pointing the caller at `docs/adr/0005-bounded-contexts.md`, and
exit without writing any output. There is NO fallback to a repo-wide
`UBIQUITOUS_LANGUAGE.md` — that file is an explicit anti-pattern in
EVOKORE-MCP.

## Adapted From Upstream

This adapter is derived from
[`ubiquitous-language/SKILL.md`](../../upstream/mattpocock-skills/ubiquitous-language/SKILL.md)
in the `mattpocock/skills` submodule pinned at
`90ea8eec03d4ae8f43427aaf6fe4722653561a42`. The upstream extracts a
DDD-style glossary from "the current conversation" and writes one
file at the project root.

To read the upstream body without loading the full file, prefer:

```text
nav_read_anchor SKILLS/upstream/mattpocock-skills/ubiquitous-language/SKILL.md <anchor-id>
```

License: MIT, Copyright (c) 2026 Matt Pocock. See repo-root `NOTICE` and
`SKILLS/upstream/mattpocock-skills/LICENSE`.

## EVOKORE-Specific Adaptations

Concrete deltas vs the upstream skill:

- **No repo-wide glossary.** The upstream writes a single
  `UBIQUITOUS_LANGUAGE.md` at the project root. EVOKORE-MCP rejects
  this as a DDD anti-pattern (see ADR-0005 "Decision" section: the
  same word legitimately means different things across contexts). This
  adapter writes one glossary per context only.
- **No interactive interview.** The upstream "scans the conversation"
  and proposes terms in a chat dialog. EVOKORE is autonomous — this
  adapter reads append-only artifacts instead: replay JSONL, evidence
  JSONL, and `src/` identifiers filtered to the named context's
  modules.
- **Always context-scoped.** The first line of every glossary file is
  the bounded-context name and a back-link to ADR-0005. There is no
  unscoped run mode.
- **Source citations are required.** Each term MUST cite at least one
  source: a `src/<file>.ts` identifier, a replay JSONL line range, or
  an evidence JSONL line. The upstream allows undocumented opinion;
  EVOKORE requires evidence (per the project's "Evidence Capture" hook
  philosophy).
- **Composition phrasing.** When a glossary surface ambiguity that
  warrants an architectural change, the skill emits literal "invoke
  improve-codebase-architecture skill" phrasing so the static
  composition graph (`derive-skill-composition.js`) can edge to it.
- **Trigger-explicit description.** Frontmatter `description` is
  rewritten in EVOKORE's "Use when ..." form so `resolve_workflow`
  semantic ranking can rank this skill above deep reference leaves.

## Output Path

Glossary files are written under this skill's own directory so they
live alongside the rules that produced them and cannot be confused
with a repo-wide artifact:

```text
SKILLS/CONTEXT/ubiquitous-language/glossaries/<context-slug>.md
```

Where `<context-slug>` is the kebab-case slug listed in the **Bounded
Context Required** section above. Existing files are read first and

From mattmre/EVOKORE-MCP-PUBLIC, MIT.

More from mattmre/EVOKORE-MCP-PUBLIC