| name | glossary |
| description | Use when the user wants to nail down domain terms, resolve terminology ambiguities, or build a shared language for a module or repo. Drills vocabulary one question at a time and writes to the project GLOSSARY.md. |
Glossary
Overview
Drills domain vocabulary one question at a time, then writes to the project GLOSSARY.md.
Core Workflow
Step 1 — Locate the target file
Goal: Identify which GLOSSARY.md to write to.
Exit criterion: Target file path is known.
Infer from context:
- Conversation about a specific module →
<module>/GLOSSARY.md (preferred) or <module>/__docs/GLOSSARY.md (if the module dir is in PATH and docs live there)
- Repo-wide → root
GLOSSARY.md
- Unclear → ask once: "Which module is this glossary for? Or is it repo-wide?"
If the file already exists at either location, read it before drilling — don't duplicate or contradict existing terms.
Step 2 — Drill
Goal: Resolve every term one at a time.
Exit criterion: All terms are settled and the user confirms the glossary is ready to write.
How to ask
Interview me relentlessly about every term of this plan until we reach a shared understanding.
Walk down each branch of the design tree, resolving dependencies between decisions one-by-one.
For each question, provide your recommended answer.
Ask the questions one at a time, waiting for feedback on each question before continuing.
Wait for an answer before moving to the next question.
Once all terms are resolved, present a summary and ask: "Ready to write the glossary?"
What to ask
Challenge against the glossary:
When I uses a term that conflicts with the existing language in GLOSSARY.md, call it out immediately.
Example: "Your glossary defines 'cancellation' as X, but you seem to mean Y — which is it?"
Sharpen fuzzy language:
When I uses vague or overloaded terms, propose a precise canonical term.
Example: "You're saying 'account' — do you mean the Customer or the User? Those are different things."
Discuss concrete scenarios:
When domain relationships are being discussed, stress-test them with specific scenarios.
Invent scenarios that probe edge cases and force the user to be precise about the boundaries between concepts.
Cross-reference with code:
When I state how something works, check whether the code agrees.
If you find a contradiction, surface it: "Your code cancels entire Orders, but you just said partial cancellation is possible — which is right"
Step 3 — Write
Goal: Write the complete glossary to the target file.
Exit criterion: File written and confirmed.
Update the glossary — all terms, relationships, flagged ambiguities, and example dialogue.
Use the format in GLOSSARY-FORMAT.md.
Step 4 — Update root index
Goal: Keep the root GLOSSARY.md as an accurate index of all sub-module glossaries.
Exit criterion: Root file lists this sub-module glossary with a current one-line description.
Skip if: Skip this step if the target file IS the root GLOSSARY.md.
Update the root GLOSSARY.md to reference the updated sub-glossary.
Use the format in GLOSSARY-INDEX-FORMAT.md.
Common Rationalizations
| Rationalization | Reality |
|---|
| "I'll write each term as it's resolved" | Relationships need all terms. Write once, at the end. |
| "Target is obvious from context" | One question beats writing to the wrong file. |
| "I know this term from prior context" | Prior context isn't canonical. Drill it. |
Checklist
