context-and-decisions

Domain Context and Decision Handoff

Govern “what these business terms mean” separately from “why this option was chosen.” Do not create an empty shell when no stable content exists.

Domain Context Artifact: Domain Language Only

When terms require repeated explanation, one term has multiple meanings, or unclear language causes module-boundary errors, first reuse the repository's existing glossary/domain-model document or the context role in .governance/docs-map.json. If an existing context map identifies separate business contexts, follow its links to the relevant glossary; ask when the topic's owner is unclear. Different contexts may legitimately use the same word differently. Do not create a glossary for every directory or impose one meaning across unrelated contexts. Only when no equivalent exists and a term has been resolved should you propose the default CONTEXT.md from templates/context.example.md. Obtain the user's explicit approval to create that new artifact before writing it, and stay within the authorized documentation scope. General permission to update documentation does not itself approve a new artifact; editing an existing mapped glossary within the authorized scope does not require a new-artifact approval.

Record only:

• domain terms and precise definitions;
• relationships among core concepts;
• confirmed ambiguities and the chosen interpretation;
• ambiguities still awaiting confirmation from a domain owner.

Do not include implementation details, current state, task schedules, full requirements, decision rationale, or history. Keep those in code/MAP, STATUS/Issue Tracker, Spec, ADR, and LOG respectively. Terms must be traceable to code, contracts, or business evidence. Mark unconfirmed items as needs confirmation; do not guess.

Refine Language During the Conversation

This is an active modeling workflow, not a requirement to rewrite the glossary whenever another skill reads it.

• Challenge contradictions. Compare the user's wording with the glossary. If “cancellation” already means cancelling an entire order but the request permits cancelling one line, explain that distinction and ask which meaning is intended; do not silently redefine the term.
• Separate overloaded concepts. For “account,” establish whether the speaker means the customer organization, a person's login, or a billing relationship. Propose a precise term for each distinct concept. Record rejected synonyms only where they really denote the same concept in this context.
• Probe relationships with concrete scenarios. Ask, for example, whether one customer can have multiple logins, or what happens to an invoice when only part of an order is cancelled. Scenarios expose boundaries; they are questions, not invented business rules.
• Check claims against evidence. Inspect relevant code, tests, contracts, and existing records. If the implementation cancels only whole orders, surface the mismatch with the proposed partial-cancellation rule. Code demonstrates current behavior, not the business owner's desired behavior; do not decide which is correct by yourself.
• Capture confirmed terms as they settle. Within an authorized documentation edit, update the existing glossary at that point instead of deferring all definitions until closeout. Keep definitions to one or two sentences, with a source and context-specific avoided synonyms where useful. Do not rewrite code, contracts, or accepted decisions merely to match a proposed term. In discussion-only or read-only work, present the proposed wording without writing files.