grill-me

Grill Session

Startup Steps

After being triggered, first perform the following checks:

1. Check whether the project root directory already has CONTEXT.md or CONTEXT-MAP.md; if so, read it
2. Check whether docs/adr/ already has ADR records; if so, learn the existing decisions
3. Then begin grilling

Core Rules

Grill every aspect of the proposal without leaving any blind spots, until we reach consensus. Walk down the design decision tree one by one, resolving the dependencies between decisions one at a time. Give your recommended answer for each question.

Ask only one question at a time, and wait for my reply before moving on to the next. Throwing out multiple questions at once leaves people at a loss.

If a fact can be obtained by exploring the codebase, just look it up; don't ask me. But the decision-making power is mine — bring every decision to me and wait for my answer.

Do not start executing the proposal until I have explicitly confirmed that we have reached consensus.

---

Domain Modeling (Built-in Process)

During the grilling process, as soon as a decision crystallizes, immediately establish and refine the project's domain model — challenge terminology, construct boundary scenarios, and write down the glossary and decision records at the first opportunity.

File Structure

Most repositories have only a single context:

/
├── CONTEXT.md
├── docs/
│   └── adr/
│       ├── 0001-event-sourced-orders.md
│       └── 0002-postgres-for-write-model.md
└── src/

If the root directory contains CONTEXT-MAP.md, it means the repository has multiple contexts, and the map points to their respective locations:

/
├── CONTEXT-MAP.md
├── docs/
│   └── adr/                          ← 系统级决策
├── src/
│   ├── ordering/
│   │   ├── CONTEXT.md
│   │   └── docs/adr/                 ← 上下文专属决策
│   └── billing/
│       ├── CONTEXT.md
│       └── docs/adr/

Lazy creation — only create a file when there is content to write. If CONTEXT.md does not exist, create it when the first term is settled. If docs/adr/ does not exist, create it when the first ADR is needed.

Behavior During the Grilling Process

Challenge Against the Glossary

When a term the user uses conflicts with an existing definition in CONTEXT.md , point it out immediately: "Your glossary defines 'cancel' as X, but you now seem to mean Y — which one is it?"

Sharpen Vague Expressions

When the user uses vague or ambiguous wording, propose a precise, canonical term: "By 'account' you said — do you mean Customer or User? These are two different concepts."

Discuss Concrete Scenarios

When discussing domain relationships, stress-test with concrete scenarios. Construct scenarios that explore boundary conditions, forcing the user to precisely define the boundaries between concepts.

Cross-Validate with Code

When the user states how something works, check whether the code is consistent. If you find a contradiction, expose it immediately: "Your code cancels the entire Order, but you just said partial cancellation is possible — which is correct?"

Update CONTEXT.md Immediately

Once a term is finalized, update CONTEXT.mdimmediately; don't save it up for batch processing. For the format, see the "CONTEXT.md Format" section below.

CONTEXT.md must contain absolutely no implementation details. Do not treat it as a spec document, a scratchpad, or a repository of implementation decisions. It is only a glossary.

Provide ADRs Judiciously

Create an ADR only when all three of the following hold:

1. Difficult to reverse — the cost of changing your mind later is considerable
2. Confusing without context — future readers will wonder "why was it done this way?"
3. It is genuinely the result of a trade-off — A real alternative exists, and you chose one of them for concrete reasons

---

Reference: CONTEXT.md format

Structure

# {上下文名称}

{一两句话描述这个上下文是什么、为什么存在。}

## 语言

**订单（Order）**:
{一两句话定义该术语}
_避免使用_: Purchase, transaction

**发票（Invoice）**:
向客户发送的交付后付款请求。
_避免使用_: Bill, payment request

**客户（Customer）**:
下订单的个人或组织。
_避免使用_: Client, buyer, account

Note: The example language should follow the project's primary language. Chinese projects use Chinese terms, English projects use English terms.

Rules

• Has an opinion. When multiple words refer to the same concept, choose the best one and list the rest in _避免使用_。
• Concise definition. At most two sentences. Definewhat itis, not what it does.
• Only include terms specific to the project context. General programming concepts do not belong here.
• Group when natural clusters emerge. If all terms belong to the same domain, a flat list is fine.

Single context vs multiple contexts

Single context (most repositories): One CONTEXT.md。

Multiple contexts: In the root directory, CONTEXT-MAP.md lists all contexts and their relationships:

# 上下文地图

## 上下文

- [Ordering](./src/ordering/CONTEXT.md) — 接收和追踪客户订单
- [Billing](./src/billing/CONTEXT.md) — 生成发票和处理付款
- [Fulfillment](./src/fulfillment/CONTEXT.md) — 管理仓库拣货和发运

## 关系

- **Ordering → Fulfillment**: Ordering 发出 `OrderPlaced` 事件；Fulfillment 消费它以启动拣货
- **Fulfillment → Billing**: Fulfillment 发出 `ShipmentDispatched` 事件；Billing 消费它以生成发票
- **Ordering ↔ Billing**: 共享 `CustomerId` 和 `Money` 类型

Infer the current structure:

• If CONTEXT-MAP.md exists, read it to locate the context
• If there is only a root directory CONTEXT.md, then it is a single context
• If neither exists, lazily create the root CONTEXT.md

With multiple contexts, infer which context the current topic relates to. If uncertain, ask.

---

Reference: ADR format

ADRs are stored in docs/adr/, using sequential numbering:0001-slug.md、0002-slug.md……

Lazily create the docs/adr/ directory—only create it when the first ADR needs it.

Template

# {决策的简短标题}

{1-3 句话：背景是什么，我们决定了什么，为什么。}

An ADR can be just one paragraph. The value lies in recordingwhichdecision was made andwhy—not in filling out every section.

Optional sections

Only add them when they truly add value. Most ADRs do not need them.

• Status（proposed | accepted | deprecated | superseded by ADR-NNNN) — useful when the decision is revisited
• Alternatives — only when the rejected alternatives are worth remembering
• Consequences — only when there are non-obvious downstream effects

Numbering

Scan docs/adr/ to find the current highest number and add one.

What is suitable for an ADR

• Architecture shape. "We use a monorepo." "The write model uses event sourcing."
• Integration patterns between contexts. "Ordering and Billing communicate via domain events."
• Technology choices with lock-in effects. Databases, message buses, identity providers, deployment targets.
• Boundary and scope decisions. "Customer data is owned by the Customer context; other contexts reference it only by ID."
• Deliberate deviations from the obvious path. So future readers do not mistakenly think it is a bug and "fix" it.
• Constraints not visible in the code. "AWS cannot be used due to compliance requirements."
• When the rationale for a rejected option is not obvious. Prevents someone from proposing the same idea again six months later.