Collaborative Judgment — defaults¶
Loaded by Config Resolution when a project has no override, or as the base layer under an overlay.
1. The presentation format¶
Use this shape. It is short on purpose: the user should be able to answer from a phone.
**Decision: <the question, in one line>**
_Reversibility: one-way / reversible_ · _Blocking: yes / no_
**A. <name>** — <what it means in this codebase, one or two sentences>
· Gains: <the specific benefit>
· Costs: <the specific cost>
· Fits when: <the condition that makes this right>
**B. <name>** — …
**Recommendation: A**, because <the reason grounded in this project's constraints>.
Rules that matter more than the layout:
- Name options after what they are, not "Option 1 / Option 2".
A. Synchronous call with a circuit breakeris answerable;Option 1requires scrolling back. - One line of consequence beats a paragraph of theory. The user knows what a saga is. They do
not know that in this service it means the
orderstable gains a state machine and three new compensating handlers. - State what happens if they do not answer. If you will proceed with the recommendation, say so — that turns a blocking question into an informed default.
2. Reversibility, and how much ceremony a decision deserves¶
| Class | Examples | Ceremony |
|---|---|---|
| One-way | Public API shape, published event schema, which service owns a piece of data, service boundaries, choice of datastore semantics | Always present options; record in .msskills/decisions.md; do not proceed on assumption |
| Costly to reverse | Sync vs async integration, orchestration vs choreography, consistency model, auth model | Present options; recommend; proceed on the recommendation only if the user said to keep moving |
| Reversible | Internal class structure, library choice behind a port, retry parameters, log format | Decide; state the choice in one line; move on |
| Trivial | Naming, file layout, formatting | Decide silently; follow existing conventions |
The failure mode in both directions is real. Asking about trivia trains the user to stop reading your questions. Assuming on a one-way door produces a migration.
3. Trade-offs that recur in microservices¶
When one of these surfaces, it is almost always a genuine judgment call. Present it.
| Decision | Pulls one way | Pulls the other |
|---|---|---|
| Synchronous call vs event | Simple to reason about, immediate consistency, easy debugging | Temporal coupling: the caller's availability is now the product of both services' |
| Strong vs eventual consistency | Users and auditors understand "it is correct now" | Cross-service transactions cost availability and add distributed locking |
| Orchestration vs choreography | An orchestrator makes the flow readable and debuggable in one place | Choreography avoids a central bottleneck but the flow exists only in everyone's heads |
| Split a service vs keep it together | Independent deploy and scale | Every split turns a method call into a network call with partial failure and a contract to version |
| Shared library vs duplication | One place to fix a bug | A shared library across services is a distributed deploy dependency; duplication is often cheaper than coupling |
| Extend an aggregate vs add one | Fewer moving parts, one transaction | An aggregate that grows past its invariant boundary becomes a contention hotspot |
| Own the data vs call for it | Owning removes a runtime dependency | Owning means replication, staleness, and a second source of truth to reconcile |
| Fail closed vs degrade | Failing closed protects correctness | Degrading protects availability; which one is right is a product decision, not a technical one |
For the domain reasoning behind each, defer to the skill that owns it — service-boundaries,
domain-modelling, cqrs-and-consistency, resilience-patterns, api-contracts.
4. Recording decisions¶
Append to .msskills/decisions.md, newest last. Create the file if it is absent.
## 2026-09-05 — Order confirmation is published as an event, not a synchronous call
**Context:** Checkout must not fail when the notification service is down.
**Options considered:** Synchronous call with circuit breaker + fallback; domain event via the outbox.
**Decision:** Domain event via the transactional outbox.
**Because:** Confirmation is not required for the order to be valid; availability of checkout
outranks immediacy of the email.
**Reversibility:** Costly — consumers will bind to the event schema.
**Consequences:** Adds an outbox table and a relay; notification becomes eventually consistent;
`OrderConfirmed` is now a published contract governed by `api-contracts`.
When a feature design document is open, the decision goes in that document's Decisions Log instead,
and .msskills/decisions.md gets a one-line pointer to it. Two copies drift; a pointer does not.
Superseding: never edit a recorded decision. Append a new one that names the entry it replaces and what changed. The history of why a system is shaped the way it is has more value than a tidy file.
5. Handling the answer¶
- The user picks an option → it is binding. Proceed with it, and do not re-litigate it later in the same session because it turned out to be more work.
- The user picks something you did not offer → record it as chosen, and say plainly if you see a problem with it. Once they confirm, build it.
- The user says "you decide" → take your recommendation, record it with
Decided by: agent on delegation, and keep going. Delegation is an answer. - The option proves unworkable mid-implementation → stop, say what broke the assumption, and re-open the decision with what you now know. Do not silently switch to option B.