edkuksa/skills
1
0
Fork 0
mirror of https://github.com/mattpocock/skills.git synced 2026-04-30 14:03:53 +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
+23 -15
View File
@@ -27,17 +27,17 @@ Write a `UBIQUITOUS_LANGUAGE.md` file with this structure:
## Order lifecycle ## Order lifecycle
| Term | Definition | Aliases to avoid | | Term | Definition | Aliases to avoid |
|------|-----------|-----------------| | ----------- | ------------------------------------------------------- | --------------------- |
| **Order** | A customer's request to purchase one or more items | Purchase, transaction | | **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 | | **Invoice** | A request for payment sent to a customer after delivery | Bill, payment request |
## People ## People
| Term | Definition | Aliases to avoid | | Term | Definition | Aliases to avoid |
|------|-----------|-----------------| | ------------ | ------------------------------------------- | ---------------------- |
| **Customer** | A person or organization that places orders | Client, buyer, account | | **Customer** | A person or organization that places orders | Client, buyer, account |
| **User** | An authentication identity in the system | Login, account | | **User** | An authentication identity in the system | Login, account |
## Relationships ## Relationships
@@ -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. - **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. - **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. - **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. - **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. - **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. - **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. - **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 ## Re-running
When invoked again in the same conversation: 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` 1. Read the existing `UBIQUITOUS_LANGUAGE.md`
2. Incorporate any new terms from subsequent discussion 2. Incorporate any new terms from subsequent discussion
3. Update definitions if understanding has evolved 3. Update definitions if understanding has evolved
4. Mark changed entries with "(updated)" and new entries with "(new)" 4. Re-flag any new ambiguities
5. Re-flag any new ambiguities 5. Rewrite the example dialogue to incorporate new terms
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.