context-and-decisions
用 CONTEXT.md 管領域術語，難回頭的決策交給 ADR
中文翻譯
--- name: context-and-decisions description: >- 需要時，用範圍窄的 CONTEXT.md 管理穩定的領域脈絡，並把難以回頭的決策導向 ECC 既有的 architecture-decision-records skill。適用於領域術語需要反覆解釋、一個術語有多重意思、語意不清導致模組邊界出錯，或領域語意必須跟架構決策分開時。 --- # Domain Context and Decision Handoff 把「這些商業術語是什麼意思」和「為什麼選這個方案」分開管理。沒有穩定內容時，不要建立空殼。 ## Domain Context Artifact: Domain Language Only 當術語需要反覆解釋、一個術語有多重意思，或語意不清導致模組邊界出錯時，先重複使用 repository 既有的詞彙表/領域模型文件，或 `.governance/docs-map.json` 裡的 `context` 角色。如果現有的 context 地圖指出有各自獨立的商業脈絡，就順著連結去看相關的詞彙表；如果不清楚這個主題由誰負責，就去問。不同的脈絡可能合理地用同一個詞表達不同意思。不要為每個目錄都建一份詞彙表，也不要在互不相關的脈絡之間強加同一個意思。只有在沒有對等文件、而且某個術語已經釐清時，才提議使用 `templates/context.example.md` 裡預設的 `CONTEXT.md`。寫入之前，要取得使用者明確同意建立這份新成品，並且留在被授權的文件範圍內。一般性的更新文件許可，本身並不等於核准新成品；在授權範圍內編輯已經對應好的既有詞彙表，則不需要新成品的核准。 只記錄： - 領域術語和精確的定義； - 核心概念之間的關係； - 已確認的模糊之處，以及選定的詮釋； - 仍在等領域負責人確認的模糊之處。 不要包含實作細節、目前狀態、任務排程、完整需求、決策理由或歷史。這些要分別放在 code/MAP、STATUS/Issue Tracker、Spec、ADR 和 LOG。術語必須能追溯到程式碼、契約或商業證據。未確認的項目要標成 `needs confirmation`，不要猜。 ## Refine Language During the Conversation 這是一個主動的建模流程，不是每當別的 skill 讀到詞彙表就要重寫它。 - **質疑矛盾。** 把使用者的用詞跟詞彙表比對。如果「取消（cancellation）」已經是指取消整張訂單，但需求卻允許取消單一品項，就說明這個差異，並問清楚是哪個意思；不要默默重新定義術語。 - **拆開被過度使用的概念。** 對於「帳號（account）」，要先確認說話的人指的是客戶組織、個人的登入，還是帳務關係。為每個不同的概念提出一個精確的術語。只有在這個脈絡中真的指同一個概念時，才記錄被拒絕的同義詞。 - **用具體情境探測關係。** 例如問一個客戶能不能有多個登入，或只取消部分訂單時發票會怎樣。情境會揭露邊界；它們是問題，不是捏造出來的商業規則。 - **用證據檢驗說法。** 檢查相關的程式碼、測試、契約和既有紀錄。如果實作只會取消整張訂單，就把這個跟提議中的部分取消規則的不一致點浮現出來。程式碼顯示的是目前的行為，不是商業負責人期望的行為；不要自己決定哪個才對。 - **術語確定時就記下來。** 在被授權的文件編輯範圍內，在那個時間點更新既有的詞彙表，不要拖到收尾才一次補定義。定義限制在一兩句話，附上來源，並在有用時列出該脈絡下要避免的同義詞。不要只為了配合提議的術語而重寫程式碼、契約或已接受的決策。在純討論或唯讀的工作中，只呈現提議的措辭，不要寫檔案。 使用專案既有的詞彙表格式。新文件的話，[context 範本](templates/context.example.md)提供一個精簡的起點；沒有實質內容的區段就省略。要放的是商業專屬的概念，不是 timeout 或工具函式之類的通用程式設計詞彙。 ## ADR Handoff: Reuse the Existing Capability 這個 skill 不另外定義第二套 ADR 目錄、編號方式、生命週期或範本。當某個決策難以回頭、沒有脈絡會讓未來的讀者困惑，而且涉及真正的取捨時： 1. 讀取並執行 `architecture-decision-records`，保留 repository 既有的 ADR 位置、格式，以及初始化和寫入時的明確核准關卡。 2. 如果沒有既定慣例，就讓那個 skill 選擇最小可行的位置；不要在這裡另外建一套系統。 3. 從 `CONTEXT.md`、專案地圖或相關的 Spec/Issue 連結到該 ADR，不要複製決策本文。 4. 當決策被接受、被取代或被棄用時，依照 living-document 規則，把事件附加到專案歷史裡。 例行的實作細節、容易回復的變更和短期的實驗，不需要 ADR。 ## When to Activate - 領域術語被反覆重新解釋，或語意不清導致實作漂移。 - 專案需要一個穩定的領域語言入口，但沒有對等的文件。 - Context 的工作挖出了應該交給 `architecture-decision-records` 的持久決策。 只是在一般的 bug 修復中使用已經確立的詞彙，不需要建模 session，也不需要新文件。 ## When to Use 當穩定的領域語言需要一個有證據支撐的歸宿，或是 context 的工作揭露了屬於 repository 既有 ADR 系統、難以回頭的決策時，使用這個 skill。 ## How It Works 1. 如果有對應好的 context 或詞彙表成品，就重複使用；只有在沒有對等的事實來源、而且使用者已明確核准建立這份新成品時，才建立 `CONTEXT.md`。 2. 質疑互相衝突的用語、探測具體的邊界情況，並在記錄已確認的定義和關係之前，拿程式碼和契約交叉檢查說法。把未解決的詮釋明確保留下來，不要混入實作或任務狀態。 3. 把持久的取捨導向 `architecture-decision-records`，並連結產生的 ADR，不要把它的理由複製進 context 文件。 4. 排程、阻擋項和執行狀態，留在既有的 issue tracker 裡。 ## Examples - 把一個被過度使用的商業術語定義一次，並連結到能證明它意思的程式碼或契約。 - 在領域負責人解決之前，把某個領域詮釋標成 `needs confirmation`。 - 把一個持久的儲存或邊界決策交給既有的 ADR 流程，並從 context 成品連結過去。 ## Anti-Patterns - 把目前的任務、排程、完整需求或實作細節複製進 `CONTEXT.md`。 - 為了完整而建立空的 context 檔案，或第二套 ADR 系統。 - 把未確認的領域詮釋當成事實，或把 ADR 本文複製進地圖和紀錄裡。 - 把不同的商業概念改名當同義詞，或強迫各自獨立的脈絡塞進同一份通用詞彙表。 - 把更新詞彙表當成可以更改實作的許可，或把程式碼當成預期商業規則的證明。 ## Related Skills - `architecture-decision-records`：難以回頭的決策唯一的 ADR 方法論。 - `living-docs-governance`：專案地圖、狀態和歷史的生命週期維護。 - `docs-governance`：跨能力的路由和收尾順序。 ## Scheduling and Task Boundary 任務、狀態、阻擋項和排程，留在專案既有的 tracker（例如 GitHub Issues 或 Linear），把它當作唯一的事實來源。只有在沒有外部 tracker、而且專案明確採用時，才使用本地的 `.scratch/`。不要把排程放進 `CONTEXT.md`、ADR、PROJECT_STATUS 或歷史索引資料庫。 ## Attribution 主動的術語精煉流程，改編自 Matt Pocock 以 MIT 授權發布的 `domain-modeling` skill。見[來源與改編的界線](references/source.md)。ECC 既有的 ADR 流程仍是決策記錄唯一的負責者。
英文原文
--- name: context-and-decisions description: >- Govern stable domain context with a narrowly scoped CONTEXT.md when needed, and route hard-to-reverse decisions to ECC's existing architecture-decision-records skill. Use when domain terms require repeated explanation, one term has multiple meanings, unclear language causes module-boundary mistakes, or domain semantics must remain separate from architecture 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. Use the project's existing glossary format. For a new document, the [context template](templates/context.example.md) provides a compact starting point; omit sections without real content. Include business-specific concepts, not generic programming vocabulary such as timeouts or utility functions. ## ADR Handoff: Reuse the Existing Capability This skill does not define a second ADR directory, numbering scheme, lifecycle, or template. When a decision is hard to reverse, would confuse a future reader without context, and involves a real tradeoff: 1. Read and execute `architecture-decision-records`, preserving the repository's existing ADR location, format, and explicit approval gates for initialization and writing. 2. If no convention exists, let that skill choose the minimum viable location; do not create a separate system here. 3. Link to the ADR from `CONTEXT.md`, the project map, or the relevant Spec/Issue instead of copying the decision body. 4. When a decision is accepted, superseded, or deprecated, append an event to project history according to the living-document rules. Routine implementation details, easily reversible changes, and short-lived experiments do not need ADRs. ## When to Activate - Domain terms are repeatedly re-explained or ambiguous language causes implementation drift. - The project needs a stable domain-language entry point but has no equivalent document. - Context work uncovers a durable decision that should be handed to `architecture-decision-records`. Merely consuming established vocabulary during an ordinary bug fix does not require a modeling session or new documentation. ## When to Use Use this skill when stable domain language needs one evidence-backed home, or when context work reveals a hard-to-reverse decision that belongs in the repository's existing ADR system. ## How It Works 1. Reuse the mapped context or glossary artifact when one exists; create `CONTEXT.md` only when no equivalent source of truth is available and the user has explicitly approved creating that new artifact. 2. Challenge conflicting language, probe concrete edge cases, and cross-check claims against code and contracts before recording confirmed definitions and relationships. Keep unresolved interpretations explicit without mixing in implementation or task state. 3. Route durable tradeoffs to `architecture-decision-records` and link the resulting ADR instead of copying its rationale into context documents. 4. Keep schedules, blockers, and execution status in the existing issue tracker. ## Examples - Define an overloaded business term once and link it to the code or contract that proves its meaning. - Mark a domain interpretation as `needs confirmation` until a domain owner resolves it. - Hand off a durable storage or boundary decision to the existing ADR workflow and link it from the context artifact. ## Anti-Patterns - Copying current tasks, schedules, full requirements, or implementation details into `CONTEXT.md`. - Creating empty context files or a second ADR system for completeness. - Treating unconfirmed domain interpretations as facts, or copying ADR bodies into maps and logs. - Renaming distinct business concepts as synonyms, or forcing separate contexts into one universal glossary. - Treating a glossary update as permission to change implementation, or treating code as proof of the intended business rule. ## Related Skills - `architecture-decision-records`: the sole ADR methodology for hard-to-reverse decisions. - `living-docs-governance`: lifecycle maintenance for the project map, status, and history. - `docs-governance`: cross-capability routing and closeout order. ## Scheduling and Task Boundary Keep tasks, status, blockers, and schedules in the project's existing tracker, such as GitHub Issues or Linear, as the single source of truth. Use local `.scratch/` only when no external tracker exists and the project explicitly adopts it. Do not put schedules in `CONTEXT.md`, ADRs, PROJECT_STATUS, or the history index database. ## Attribution The active terminology-refinement workflow adapts Matt Pocock's MIT-licensed `domain-modeling` skill. See [source and adaptation boundaries](references/source.md). ECC's existing ADR workflow remains the sole decision-record owner.