From e7df78bb81da39c537be810e622d2b90bbdc7dc5 Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Tue, 19 May 2026 14:40:27 +0100 Subject: [PATCH] Removed relationships, example dialogue, and flagged ambiguities from CONTEXT.md template --- .../grill-with-docs/CONTEXT-FORMAT.md | 18 ++---------------- 1 file changed, 2 insertions(+), 16 deletions(-) diff --git a/skills/engineering/grill-with-docs/CONTEXT-FORMAT.md b/skills/engineering/grill-with-docs/CONTEXT-FORMAT.md index ddfa247..0830255 100644 --- a/skills/engineering/grill-with-docs/CONTEXT-FORMAT.md +++ b/skills/engineering/grill-with-docs/CONTEXT-FORMAT.md @@ -10,7 +10,7 @@ ## Language **Order**: -{A concise description of the term} +{A one or two sentence description of the term} _Avoid_: Purchase, transaction **Invoice**: @@ -20,27 +20,13 @@ _Avoid_: Bill, payment request **Customer**: A person or organization that places orders. _Avoid_: Client, buyer, account - -## Relationships - -- An **Order** produces one or more **Invoices** -- An **Invoice** belongs to exactly one **Customer** - -## Example dialogue - -> **Dev:** "When a **Customer** places an **Order**, do we create the **Invoice** immediately?" -> **Domain expert:** "No — an **Invoice** is only generated once a **Fulfillment** is confirmed." - -## Flagged ambiguities - -- "account" was used to mean both **Customer** and **User** — resolved: these are distinct concepts. ``` ## Rules - **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, call it out in "Flagged ambiguities" with a clear resolution. -- **Keep definitions tight.** One sentence max. Define what it IS, not what it does. +- **Keep definitions tight.** One or two sentences max. Define what it IS, not what it does. - **Show relationships.** Use bold term names and express cardinality where obvious. - **Only include terms specific to this project's context.** General programming concepts (timeouts, error types, utility patterns) don't belong even if the project uses them extensively. Before adding a term, ask: is this a concept unique to this context, or a general programming concept? Only the former belongs. - **Group terms under subheadings** when natural clusters emerge. If all terms belong to a single cohesive area, a flat list is fine.