Keep asking about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one at a time. Give your recommended answer for each question.
Ask one question at a time, and wait for feedback on each question before continuing.
If a question can be answered by exploring the codebase, explore the codebase.
Domain awareness
When exploring the codebase, also look for existing documentation:
File structure
Most repos have only one context:
/
├── CONTEXT.md
├── docs/
│ └── adr/
│ ├── 0001-event-sourced-orders.md
│ └── 0002-postgres-for-write-model.md
└── src/
If CONTEXT-MAP.mdexists under root, the repo has multiple contexts. The map points to the location of each context:
/
├── CONTEXT-MAP.md
├── docs/
│ └── adr/ ← system-wide decisions
├── src/
│ ├── ordering/
│ │ ├── CONTEXT.md
│ │ └── docs/adr/ ← context-specific decisions
│ └── billing/
│ ├── CONTEXT.md
│ └── docs/adr/
Create files lazily on demand: only create them when you have content to write. If there is no CONTEXT.md, create it when the first term is resolved. If there is no docs/adr/, create it when the first ADR is needed.
During the session
Challenge against the glossary
When a term the user uses conflicts with existing language in CONTEXT.md , point it out immediately. "Your glossary defines 'cancellation' as X, but you now seem to mean Y. Which one is it?"
Sharpen fuzzy language
When the user uses vague or overloaded terms, propose a precise canonical term. "You say 'account', do you mean Customer or User? They are different things."
Discuss concrete scenarios
When discussing domain relationships, stress-test with concrete scenarios. Invent scenarios that probe edge cases, forcing the user to define conceptual boundaries precisely.
Cross-reference with code
When the user explains how something works, check whether the code is consistent. If you find a contradiction, show it directly: "Your code cancels entire Orders, but you just said partial cancellation is possible, which is correct?"
Update CONTEXT.md inline
When a term is resolved, update CONTEXT.mdimmediately. Do not batch them up; capture them as they happen. Use the format in CONTEXT-FORMAT.md .
Do not tie CONTEXT.md to implementation details. Include only terms that are meaningful to domain experts.
Offer ADRs sparingly
Only propose creating an ADR when all three of the following are true:
- Hard to reverse — the cost of changing your mind later is meaningful
- Surprising without context — future readers will wonder "why was it done this way?"
- The result of a real trade-off — real alternatives exist, and a choice was made based on concrete reasons
If any one is missing, skip the ADR. Use the format in ADR-FORMAT.md .