edkuksa/skills
1
0
Fork 0
mirror of https://github.com/mattpocock/skills.git synced 2026-04-30 22:13:54 +07:00
Code Issues Packages Projects Releases Wiki Activity

Refactor glossary tables and enhance example dialogue in Ubiquitous Language skill

Browse Source
This commit is contained in:
Matt Pocock
2026-03-26 19:57:24 +00:00
parent 98fecc7619
commit eebfb3c99a
1 changed files with 23 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files
ubiquitous-language/SKILL.md
+19 -11
View File
@@ -28,14 +28,14 @@ Write a `UBIQUITOUS_LANGUAGE.md` file with this structure:
## Order lifecycle
| Term | Definition | Aliases to avoid |
|------|-----------|-----------------|
| ----------- | ------------------------------------------------------- | --------------------- |
| **Order** | A customer's request to purchase one or more items | Purchase, transaction |
| **Invoice** | A request for payment sent to a customer after delivery | Bill, payment request |
## People
| Term | Definition | Aliases to avoid |
|------|-----------|-----------------|
| ------------ | ------------------------------------------- | ---------------------- |
| **Customer** | A person or organization that places orders | Client, buyer, account |
| **User** | An authentication identity in the system | Login, account |
@@ -60,12 +60,27 @@ Write a `UBIQUITOUS_LANGUAGE.md` file with this structure:
- **Be opinionated.** When multiple words exist for the same concept, pick the best one and list the others as aliases to avoid.
- **Flag conflicts explicitly.** If a term is used ambiguously in the conversation, call it out in the "Flagged ambiguities" section with a clear recommendation.
- **Only include terms relevant for domain experts.** Skip the names of modules or classes unless they have meaning in the domain language.
- **Keep definitions tight.** One sentence max. Define what it IS, not what it does.
- **Show relationships.** Use bold term names and express cardinality where obvious.
- **Only include domain terms.** Skip generic programming concepts (array, function, endpoint) unless they have domain-specific meaning.
- **Group terms into multiple tables** when natural clusters emerge (e.g. by subdomain, lifecycle, or actor). Each group gets its own heading and table. If all terms belong to a single cohesive domain, one table is fine — don't force groupings.
- **Write an example dialogue.** A short conversation (3-5 exchanges) between a dev and a domain expert that demonstrates how the terms interact naturally. The dialogue should clarify boundaries between related concepts and show terms being used precisely.
<example>
## Example dialogue
> **Dev:** "How do I test the **sync service** without Docker?"
> **Domain expert:** "Provide the **filesystem layer** instead of the **Docker layer**. It implements the same **Sandbox service** interface but uses a local directory as the **sandbox**."
> **Dev:** "So **sync-in** still creates a **bundle** and unpacks it?"
> **Domain expert:** "Exactly. The **sync service** doesn't know which layer it's talking to. It calls `exec` and `copyIn` — the **filesystem layer** just runs those as local shell commands."
</example>
## Re-running
When invoked again in the same conversation:
@@ -73,12 +88,5 @@ When invoked again in the same conversation:
1. Read the existing `UBIQUITOUS_LANGUAGE.md`
2. Incorporate any new terms from subsequent discussion
3. Update definitions if understanding has evolved
4. Mark changed entries with "(updated)" and new entries with "(new)"
5. Re-flag any new ambiguities
6. Rewrite the example dialogue to incorporate new terms
## Post-output instruction
After writing the file, state:
> I've written/updated `UBIQUITOUS_LANGUAGE.md`. From this point forward I will use these terms consistently. If I drift from this language or you notice a term that should be added, let me know.
4. Re-flag any new ambiguities
5. Rewrite the example dialogue to incorporate new terms