domain-modeling

Model the domain

Build a precise shared understanding of the concepts that matter to the current decision. Read existing glossaries, context maps, ADRs, code, and tests when they provide relevant evidence.

Sharpen the model

• Identify overloaded terms, hidden distinctions, and conflicting definitions.
• Use concrete scenarios and edge cases to test whether concepts and boundaries hold.
• Compare the stated model with behavior in the code and surface material contradictions.
• Propose clear language when ambiguity is blocking progress, while respecting established repository terminology that remains accurate.

Ask the user to resolve a term only when their intent cannot be inferred safely and the distinction affects the outcome.

Record durable knowledge proportionally

Update a glossary or context map when the user requests it or when a resolved term is durable, project-specific, and useful beyond the current conversation. Follow an existing repository format first; otherwise use the context format as a lightweight starting point.

Record an ADR only when a decision is costly to reverse, surprising without its context, and based on a meaningful tradeoff. Follow existing ADR conventions or use the ADR format. Do not create artifacts merely to complete the workflow.

Keep domain definitions separate from implementation plans. Report unresolved ambiguity and artifact changes explicitly.