4-connect
DDD loop 2 — connect: Domain Message Flow Modelling per use case — typed messages, coupling smells, boundary deltas handed back to decompose. Writes docs/domain/message-flows/.
- License 许可
- MIT
- 所属仓库
- baodq97/govkit
- 最近更新
- 2026-09-07
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- 4-connect
- description
- DDD loop 2 — connect: Domain Message Flow Modelling per use case — typed messages, coupling smells, boundary deltas handed back to decompose. Writes docs/domain/message-flows/.
- disable-model-invocation
- true
02 资源文件 3
- 参考文档evals/evals.json4.0 KB
- 参考文档references/coupling-heuristics.md7.0 KB
- 参考文档references/message-flow-notation.md7.1 KB
03 SKILL.md 正文
Domain Connect
"It is necessary to challenge the initial design by applying concrete use-cases to uncover hidden complexity." — ddd-crew, Connect
A context map tells you which contexts exist and that they are related. It cannot tell you whether the split works, because it never moves. A message flow moves: one real business scenario, message by message, in order, across the boundaries you just drew. That motion is what exposes the coupling — a boundary looks clean until you watch four synchronous hops cross it to satisfy one customer request.
What this skill produces: a small set of flows for the use cases that matter, plus the findings
those flows forced into the open — and, where a flow proves a boundary wrong, a proposed change
handed back to 3-decompose. Proposed, not applied: a boundary redrawn by the skill that
discovered the problem skips the reconciliation, seam, and delta-merge discipline that decomposition
owns.
Inputs
docs/domain/— contexts, relationships, and the domain events each context emits. This is the design under test.docs/domain/discovery/— the event timeline, if discovery ran. Flows built from a discovered timeline are grounded; flows built from context names alone are speculation.- The use cases to trace. If nobody names them, propose candidates and get agreement before drawing — see step 1.
Nothing under docs/domain/? Say so plainly: there is no design to challenge yet, and
3-decompose runs first. Modelling flows between contexts you are inventing as you go
produces a diagram that validates itself.
Reference files (read as needed)
references/message-flow-notation.md— the notation: message types and what each one costs in coupling, the three parts of a message (name, contents, order), separate vs combined format, the 5-to-9 message rule and why exceeding it is a finding, temporal semantics (within/after/every). Read before drawing the first flow.references/coupling-heuristics.md— the smell catalogue: what each smell looks like on a flow, what it usually means, and the boundary move that resolves it. Read at step 3.
Who to involve
- people who design, build and test software
- people who have domain knowledge
Flows are where developers and domain experts disagree productively: the developer knows what the system does, the expert knows what the business does, and the gap between those two is the finding.
Process
1. Choose the use cases — the three backbone scenarios
Trace three, not the whole backlog, and pick them by role rather than by taste:
| # | Scenario | Why this one |
|---|---|---|
| 1 | the happy path | the design's own story — if this one is ugly, nothing else will be better |
| 2 | the path with money on it | the scenario the business is actually paid for; coupling here has a price |
| 3 | the failure path | rejection, cancellation, refusal. Models are built happy-path-first, so this is where the missing messages live |
Add a fourth only for a known hotspot — something discovery flagged, or that the team already argues about.
The failure path is the one teams skip and the one that pays. A model with no rejection message anywhere is not a clean design; it is a design where nobody asked what happens when the answer is no.
A flow for a single-context CRUD scenario teaches nothing — it crosses no boundary. Say which scenarios you chose and why, and let people add the one you missed.
A prerequisite worth stating: message flows are not a discovery technique. They exist to break
a cut that already exists — "when you have an initial cut of your architecture… you can begin
design the message flows". If there is no docs/domain/ yet, this step has nothing to refute.
2. Build the flow
For each use case, in order: identify the sender (actor, bounded context, or external system), the message it sends, and the recipient. Each message carries three things — its name, its significant contents, and its order number. Type every message:
| Type | What it is | Coupling it creates |
|---|---|---|
| Event | a fact that already happened, broadcast | lowest — the sender does not know who listens |
| Command | a request that another context do something | medium — the sender knows the receiver and expects it to act |
| Query | the sender needs the receiver's data now, with a response | highest — a runtime dependency; the sender cannot proceed without the receiver being up |
Getting the type wrong is not a labelling slip. It is the whole point: a flow drawn entirely with undifferentiated arrows hides exactly the coupling this step exists to find.
Keep each diagram to 5–9 messages. Beyond that, nobody in the room can hold the flow in their head — and in practice a scenario that needs fifteen messages is telling you either that it is two scenarios or that the boundaries are wrong. Treat the overflow as a finding, not a layout problem.
When a scenario is time-dependent, be exact about which temporal relation holds: within an interval, after an event, or every period. These are three different business rules and they generate three different designs.
3. Read the flow back for coupling
This is the step that pays for the diagram. Walk the finished flow and check for the smells in
references/coupling-heuristics.md. The ones worth naming here:
- Synchronous query chain across a boundary — context A cannot act without asking B, then C. Availability multiplies and latency accumulates. Usually the data is on the wrong side, or B should publish a read model A owns a copy of.
- Cycle inside one use case — A → B → A. Two contexts that must talk back and forth to complete one scenario are temporally coupled; often they are one context wearing two names.
- Distributed invariant — one business rule enforced across two contexts within the flow. Either the rule belongs to a single aggregate, or the business must accept eventual consistency and name the compensating action. Leaving it unstated is how double-bookings ship.
- God context — one context appears in every flow, usually as a coordinator forwarding messages. Orchestration is legitimate; a context that decides nothing of its own is a hop, not a boundary.
- Pass-through — a context receives a message and forwards it without making a decision.
- Chatty pair — two contexts exchanging many messages in one flow. Count them; a pair that talks more inside a scenario than either talks to anyone else is a candidate merge.
Every finding gets: the flow it came from, the messages that show it, and what it would take to resolve it. A smell with no evidence attached is an opinion.
4. Feed findings back — do not redraw
Two conditions refute the decomposition outright, and they are the only place in the whole modelling loop where a design is rejected by evidence rather than by opinion:
more than 9 messages in one scenario, or one context appearing at every step ⇒ go back and re-cut.
Say it in those words when either fires. It is not a diagram-tidiness note; it is the loop-back
trigger, and 3-decompose becomes stale the moment it fires.
Where a flow proves a boundary wrong, write it as a proposed change with its evidence, and hand
it to 3-decompose (update mode) to merge. Where a flow reveals a domain event nobody discovered,
hand it to 2-discover to confirm with people — do not promote your own inference to a confirmed
event.
This is the loop working as intended. The modelling process is iterative; connect is where decompose gets its corrections.
5. Emit
Write one file per flow under docs/domain/message-flows/, plus a README.md index that lists the
flows and collects every finding in one place. status: draft, owner: TBD.
Output shape
---
id: DOMAIN-FLOW-0001
title: <Use case> — domain message flow
status: draft
owner: TBD
date: <date>
contexts: [Allocation, Logistics, Billing]
---
## Scenario
<!-- one paragraph, in business language: who wants what, and what "done" means -->
## Flow
```mermaid
sequenceDiagram
actor Planner as Depot Planner
participant Logistics
participant Allocation
Planner->>Logistics: 1. ScheduleTransfer [cmd] {unitId, fromDepot, toDepot, window}
Logistics->>Allocation: 2. IsUnitAvailable? [qry] {unitId, window}
```
| # | From | Message | Type | Contents | To | When |
|---|---|---|---|---|---|---|
| 1 | Depot Planner | `ScheduleTransfer` | command | unitId, fromDepot, toDepot, window | Logistics | — |
| 2 | Logistics | `IsUnitAvailable?` | query | unitId, window **→** available, freeFrom | Allocation | — |
| 3 | Logistics | `TransferLapsed` | event | unitId | Allocation | **after** 30 min of no confirmation |
**A query carries its response in the same row, after a `→`.** The notation draws a query and its
answer as one unit precisely because the sender is *blocked* in between — splitting them into two
rows doubles the diagram and hides the only interesting thing about a query. Everything left of the
arrow is what the sender sends; everything right of it is what it waits for. A query with nothing
after the `→` has not been thought through: someone has to say what comes back, because the shape of
the answer is what the caller is coupled to.
**The `When` column is for time-driven messages only**, and it exists because the semantics decide
the design: **within** 5 minutes, **after** 5 minutes and **every** 5 minutes are three different
systems. Leave it `—` for a message that follows immediately from the one above. Put the trigger
here rather than in the scenario prose — a temporal rule buried in a paragraph is invisible on the
diagram, and it is usually the rule that produces the failure path nobody drew.
## Findings
| # | Smell | Evidence (messages) | What it suggests | Proposed change |
|---|---|---|---|---|
## Open questions
<!-- one line each: the question, and who could answer it -->
The README.md index carries the use-case list, why each was chosen, and the consolidated findings
table with a status column (proposed / accepted / declined) so a later reader can tell which
findings were acted on.
Hard rules
- Length budget: ≤ 90 lines per flow file. A flow longer than that is usually two scenarios. A budget caps prose, not findings: over it, cut rationale a reader can infer and anything restated from an upstream artifact — never open questions, provenance, or a stated absence.
- Never invent a message. A flow is only as real as the events, commands and queries that were
discovered or modelled. Inferring
PaymentRefundedbecause a refund "must exist somewhere" produces a diagram that validates a design against fiction. If the flow has a gap, the gap is an open question with a name attached. - Domain messages, not transport. No HTTP verbs, no queue names, no retry policy, no serialization format. The moment a flow becomes an integration design, it stops being able to challenge the boundary — every coupling problem starts looking like a technology choice.
- Type every message. An untyped arrow hides the difference between a broadcast fact and a blocking read, which is the difference the whole step exists to surface.
- A temporal rule belongs in the
Whencolumn, never only in the scenario paragraph. If the scenario says "within fifteen minutes", some message is the one that must happen within fifteen minutes — name it and put the rule on that row. Stated only in prose, the rule cannot be drawn, cannot be checked, and is invisible to everyone reading the diagram instead of the paragraph.ddd_checkreports this astemporal-rule-in-prose. - A query states what comes back.
Contentsfor a query readssent fields → returned fields. Without the→half, the row records a question nobody answered. - Propose boundary changes; never apply them.
3-decomposeowns the model — it holds the reconciliation rules, the stable ids, the human edits and the extraction seam. A boundary quietly redrawn here is a change nobody reviewed. - Findings carry evidence. Message numbers, not adjectives. "Feels coupled" is not a finding; "messages 2–5 are synchronous queries crossing three contexts before the planner gets an answer" is.
- A flow that turns out clean is a real result. Say so — a use case that crosses four contexts with four events and no queries is evidence the split is working, and it is worth recording as such.
Worked example
Input: the equipment-rental model — contexts Allocation, Logistics, Billing,
Notifications — plus a discovery hotspot about units being double-booked across depots.
Use case chosen: "Priority depot transfer, booked and billed" — the paid add-on, and the scenario touching the most contexts.
| # | From | Message | Type | To |
|---|---|---|---|---|
| 1 | Depot Planner | ScheduleTransfer |
command | Logistics |
| 2 | Logistics | IsUnitAvailable? |
query | Allocation |
| 3 | Allocation | (response) | query | Logistics |
| 4 | Logistics | ReserveUnit |
command | Allocation |
| 5 | Allocation | EquipmentAllocated |
event | — |
| 6 | Billing | TransferFeeCharged |
event | — |
Findings the flow forced out:
| Smell | Evidence | What it suggests |
|---|---|---|
| Synchronous query chain | 2–4: Logistics asks, then commands, on the same data | check-then-act across a boundary — between 2 and 4 another planner can reserve the same unit |
| Distributed invariant | the no-double-booking rule is enforced by Logistics' check but owned by Allocation's data | the rule belongs to one aggregate; Allocation should own ReserveUnit end-to-end and answer with success or rejection |
Proposed change handed back to 3-decompose: collapse the check-then-act pair into a
single ReserveUnit command that Allocation either accepts or rejects, and record the invariant as
Allocation's. This is the same double-booking hotspot discovery surfaced — the flow is what turned
it from a worry into a located defect with two message numbers on it.
Note what the example does not do: it does not move Billing into Logistics because the two
appear adjacent, and it does not silently edit docs/domain/allocation/model.yaml. It writes the
finding, names the change, and leaves the model to the skill that owns it.
04 同仓库更多 Skills
trigger-shaped
Use when the user says "plan a sprint retro"; drafts retro/notes.md for the team.
terse-unguarded
Step 2 — writes docs/x/output.json quietly.
guarded
Summarizes ledger totals into reports/monthly.csv.
open
Draft a spec. Use when asked to "draft a spec" or "write the RFC".
guarded
Deploy the thing.
working-discipline
Thinking-checkpoint discipline for substantive implementation, debugging, or autonomous work — 21 trigger-gated items (trigger → mandatory question → evidence to produce) that cut agent error and human escalation. Use before an autonomous or long-running run, when asked to "work carefully", "double-check", "làm cẩn thận", "reduce errors", "be more autonomous", or after looping twice on the same failing fix. NOT a procedure — checkpoints fire on their triggers and demand evidence, with an N/A escape valve so a strong model pays near-zero overhead.