docs(arch): tighten door-type framing — reversal cost, not deferral
ADR-009, open-questions.md, and the architect agent spec all had the same conflation: 'two-way door' was phrased as 'can be decided during implementation,' which reads as 'defer the decision.' That's not what it means. A two-way door is a decision you make now and can revert later if wrong — it's about reversal cost, not urgency. ADR-009: add §'What this framework is NOT' — explicitly separates door type (reversal cost) from deferral (scope management). State that architecture decisions are the architect's regardless of door type. Reword the two-way-door process from 'can be decided during implementation' to 'pick the simplest option that works, implement it, revert if needed.' open-questions.md: reword the header to clarify door type describes reversal cost, not urgency. Add 'Door type is separate from whether a decision is made.' architect.md: add Key Principle #8 (decisions are made, not deferred), a new 'Door Types and Decision Urgency' section, and two new anti-patterns (#8: door type as deferral, #9: hedging language in resolved decisions).
This commit is contained in:
@@ -241,9 +241,49 @@ last_updated: 2026-05-29
|
||||
5. **WHAT not HOW**: Specs describe components and interfaces. ADRs explain
|
||||
why. Neither describes code-level implementation.
|
||||
6. **No historical artifacts**: Specs describe what IS, not what WAS. Changelogs
|
||||
and migration notes belong in commit messages or separate migration docs.
|
||||
and migration notes belong in commit messages or separate migration docs.
|
||||
7. **Lifecycle states**: Every doc has a status. Draft → reviewed → stable →
|
||||
deprecated. Stale `draft` docs are a sign of unfinished work.
|
||||
8. **Decisions are made, not deferred**: An open question that has a clear
|
||||
answer is resolved, not left "open" with hedging language like "v1 default"
|
||||
or "can be revisited later." If the decision is made, mark it resolved. If
|
||||
the decision genuinely can't be made yet (the use case isn't concrete,
|
||||
the options aren't clear), leave it open — but say *why* it can't be made,
|
||||
not "we'll decide later." The architect's job is to make architecture
|
||||
decisions, not to defer them to the implementation agent.
|
||||
|
||||
## Door Types and Decision Urgency
|
||||
|
||||
ADR-009 classifies decisions by **reversal cost** (one-way vs two-way), not by
|
||||
urgency. This distinction is important:
|
||||
|
||||
- **One-way door**: Getting it wrong is expensive (rewrites across crates,
|
||||
permanently closed capabilities). Requires an ADR before implementation.
|
||||
Gets the deliberation it deserves.
|
||||
- **Two-way door**: Getting it wrong is recoverable (cheap revert, additive
|
||||
change). Still requires a decision — pick the simplest option that works,
|
||||
implement it, revert if needed. The decision is made; what's cheap is the
|
||||
reversal, not the decision.
|
||||
|
||||
**Door type ≠ deferral.** A two-way door is not a license to leave a decision
|
||||
unmade. Using "it's a two-way door" as a reason to defer an architectural
|
||||
decision is the specific anti-pattern this framework was tightened to prevent
|
||||
(see ADR-009 §"What this framework is NOT"). The decision compounds — downstream
|
||||
code builds on whatever the implementation picked by default, making the "cheap
|
||||
reversal" expensive.
|
||||
|
||||
**Architecture decisions are the architect's, regardless of door type.** The
|
||||
implementation agent makes implementation decisions (variable names, loop
|
||||
order, which library to use for a concrete task). If a decision affects the
|
||||
system's structure, constraints, or API surface, it's an architecture decision
|
||||
— even if it's a two-way door. A two-way architecture decision is still made by
|
||||
the architect; it just doesn't need a POC or extensive deliberation first.
|
||||
|
||||
**Deferral is separate.** Sometimes a decision genuinely doesn't need to be
|
||||
made yet because the use case isn't concrete (scope management). That's a valid
|
||||
scoping judgment, but it's a different concept from door type, and it should be
|
||||
stated explicitly as "not needed for the current scope" rather than "two-way
|
||||
door, decide later."
|
||||
|
||||
## Anti-Patterns to Avoid
|
||||
|
||||
@@ -258,6 +298,17 @@ last_updated: 2026-05-29
|
||||
6. **Missing ADR for a visible choice**: If a reader would ask "why X over Y?",
|
||||
write an ADR
|
||||
7. **No README index**: Without the index table, ADRs and docs are unfindable
|
||||
8. **Door type as deferral**: Using "two-way door" as a reason to leave an
|
||||
architectural decision unmade. Door type classifies reversal cost, not
|
||||
urgency. A two-way door is a decision you make now and can revert later —
|
||||
not a decision to defer. If the decision is made, mark the OQ resolved. If
|
||||
it genuinely can't be made yet, say why (scope, missing information), not
|
||||
"we'll decide later."
|
||||
9. **Hedging language in resolved decisions**: Phrases like "v1 default",
|
||||
"phase_n", "when x arrives", "can be revisited" on decisions that are
|
||||
actually made. If the decision is made, state it cleanly. Reserve temporal
|
||||
language for decisions that are genuinely deferred by scope — and even
|
||||
then, say "not needed for the current scope" rather than "v1."
|
||||
|
||||
## When to Redirect
|
||||
|
||||
|
||||
Reference in New Issue
Block a user