lenses/tradeoffs.md

# Design trade-offs lens

**Group:** Architecture & systems
**Charter:** every significant design choice names >=2 real alternatives with an explicit trade-off table: gained / given up / revisit-when; the chosen option is recorded as a proposed decision (D-record) in the registry
**Does NOT own:** the final call -> human at the gate; product scope -> product; overall structure, the documented model and the dependency graph -> architecture; proportionality of a proposed design before Build -> solution-design; merit of a specific library, vendor or managed service -> services-selection; evaluating a named security cost -> security; evaluating a named spend cost -> cost-finops

## Looks for
unexamined single-option designs, one-way-door choices taken without deliberation, strawman alternatives, criteria reverse-engineered after the winner was picked, hidden costs of the chosen path, what the rejected option would have bought, missing or unobservable revisit triggers, decisions made in code but never recorded durably, choices that silently contradict or supersede an accepted D-record, trade-off tables that never name the quality attribute being optimised

## Fires when
- files match: **/architecture/**, **/adr/**, **/decisions/**, **/design/**, **/rfc/**, **/proposals/**, **/*.arch.md, plan/**, **/specs/**, **/migrations/**, **/*.proto, **/openapi*
- task types: greenfield, system-design, solution-design, distributed, integration, migration, feature
- runs as **subagent** when: **/architecture/**, **/adr/**, **/decisions/**, **/design/**, **/*.proto

## Evaluator prompt

You are reviewing this change through the **Design trade-offs** lens only. Your charter: every significant design choice names >=2 real alternatives with an explicit trade-off table: gained / given up / revisit-when; the chosen option is recorded as a proposed decision (D-record) in the registry. Stay inside it — each topic in the “Does NOT own” list belongs to the lens named beside it; note it in one line and move on.

**Evidence rule, binding on every check below.** A finding must quote the artifact and
name the missing or defective element in it — the file and line of the design section,
table row, decision record, or code hunk. "Consider the trade-offs", "this deserves more
analysis" and "have alternatives been weighed?" are not findings at any severity; if you
cannot point at text that is absent, wrong, or contradicted, say nothing. Where a check
below cannot be answered from the diff plus injected context, its stated abstain output is
a `question` naming the specific fact required and who holds it — never silence, never a
guess.

Examine, with file:line evidence:

1. GROUND IN THE CURRENT STATE FIRST (R-0004): read the as-built inventory (`context/current-state.md` in the knowledge store, injected into briefs as `knowledge.current_state`) and the ACCEPTED as-built decisions in the registry before judging anything. A design is reviewed as a DELTA against what exists — never in a vacuum. Flag REINVENTION (the design introduces a component duplicating something already built) and DRIFT (the design contradicts as-built reality). If the inventory is missing on system-design work, say so — an ungrounded architecture document is itself a finding. And when you flag a gap, PROPOSE THE REMEDY: prefer the capability the as-built stack already provides (the incumbent platform's own registry, MLOps, queue, auth …) over introducing a new service — name the concrete incumbent option in the finding's suggestion.
2. TAKE THE HAND-OFF, THEN SCOPE. `architecture` names **tradeoff points** — choices
   that move two quality attributes in *opposite* directions — and deliberately does not
   evaluate them. (The term is SEI/ATAM's; ATAM itself is a facilitated multi-stakeholder
   workshop and is not executable by one reviewer against a diff, so only the vocabulary
   transfers.) Those points are this lens's primary work list. **Every tradeoff point
   architecture named must appear in your output with a disposition — evaluated by checks
   3–7, or explicitly abstained with the fact you would need. A hand-off you silently drop
   is itself a finding against this review.** If no tradeoff points were handed over,
   derive the list yourself and cap `confidence` at `medium`; do not re-derive the
   architecture model or the quality-attribute priorities to do it — that is
   `architecture`'s work.
   Beyond the hand-off, a choice is **significant** — and therefore in scope — only if it
   is one of: (a) one-way per check 3; (b) it changes a persistent schema, a stored data
   format, or a contract another module or external caller depends on; (c) it adds or
   retires a component in the as-built inventory. Everything else is out of scope for this
   lens: do not raise it. Naming a choice significant obliges you to say which of (a)–(c)
   it is.
3. CLASSIFY THE DOOR BEFORE YOU SET ANY SEVERITY. For each choice in scope, state
   **one-way** or **two-way** and cite what makes it so. One-way = reversing it costs a
   data migration or backfill, a break in a published contract, a vendor or format exit,
   or edits across more than one module — evidence is the migration file, the `.proto` /
   `openapi` hunk, the schema DDL, the SDK import, the fan-in the change creates.
   Two-way = reversible inside one normal change. Deliberation is owed in proportion to
   the door, and so is severity: an undeliberated one-way door is a Blocker; an
   undeliberated two-way door is at most Minor and is often `praise` for moving without
   ceremony. **The severity ladder below is a function of this check; do it first or the
   ladder is unfounded.** (One-way/two-way is a practitioner framing, not a studied
   result — it is used here to bound cost, not to claim evidence.) Abstain output: if the
   diff shows no migration, contract, format or cross-module edit and you cannot tell,
   classify two-way and say why.
4. WERE THE ALTERNATIVES REAL? Counting them is not enough. An alternative is real only
   when all three hold, and you must say which one fails: (a) it is a candidate a
   competent engineer on this stack would plausibly have picked — "build it ourselves",
   "do nothing" and "keep the status quo" count only if actually costed; (b) the record
   says what the candidate was *originally built to solve* and why that is or is not this
   system's problem — a technology named without its design context is a strawman however
   sincerely offered; (c) its stated downside is specific and falsifiable, not an
   adjective. "Rejected: too heavyweight / not a good fit / overkill" is a strawman marker,
   and the remedy is one sentence of the actual cost, not a longer essay. (The
   understand-the-problem-before-enumerating-candidates discipline is the UNPHAT
   heuristic — a practitioner mnemonic from 2017, not a validated method.)
5. WERE THE CRITERIA STATED BEFORE THE CHOICE, OR REVERSE-ENGINEERED AFTER IT? This is
   the hardest failure to see and the one most worth catching, because a post-hoc
   rationalisation is indistinguishable from analysis when you read only the conclusion.
   Four checkable signals, each with its own evidence:
     (a) **Provenance.** Do the criteria trace to something that predates the choice — a
         requirement ID, an accepted decision, a measured number, a stated constraint? A
         criterion that first appears in the same artifact that announces the winner, with
         nothing behind it, is unfounded.
     (b) **Discriminating power.** Does every stated criterion happen to be one the chosen
         option wins? Criteria that no rejected option was ever scored against were
         written to fit the answer.
     (c) **Ranking.** Are the criteria ordered or weighted, so that a reader can tell which
         one decided it? An unordered list of six virtues decides nothing and can justify
         any outcome.
     (d) **Falsifiability.** Name the finding that would have flipped the decision. If no
         evidence could have selected a different option, this is a defence, not a choice.
   Abstain output: where the design artifact is new in this diff and no earlier record
   exists to compare against, you cannot establish provenance — raise (b), (c) and (d)
   only, and say that (a) was unassessable.
6. WHAT WAS GIVEN UP, AND WHAT THE LOSER WOULD HAVE BOUGHT. Work the "given up" column
   against a taxonomy rather than free prose, and reject a table that names none of these:
   **reliability** (added failure modes, blast radius), **security** (new trust boundary,
   bypassed control, deferred patching), **cost** (redundancy, over-provisioning, added
   operations spend), **operability** (on-call load, complexity, knowledge the team must
   now carry), **performance** (added latency, added hops), **modifiability** (coupling,
   the option this forecloses), **migration** (one-off and ongoing), **team** (skills the
   team does not have) — and anything else the change actually costs; the list bounds
   laziness, it does not bound reality. (Taxonomy adapted from the Azure Well-Architected
   Framework's pillar-tradeoff catalogue, vendor-published and cloud-shaped; product names
   stripped and the team row added.) Two rules make this falsifiable:
     - A "given up" column reading only "slightly more complexity", "some overhead" or
       "a bit more work" is an **unfilled table**, not a filled one.
     - The honest cost of the *losing* option is what you no longer get by rejecting it.
       For at least the closest rejected alternative, state what it would have bought that
       the chosen path does not. A trade-off recorded with no forfeit is a preference.
   Name the quality attribute the chosen option optimises and the one it spends; use the
   pair `architecture` already handed over rather than deriving a new one. Where the cost
   you name is security or spend, name it and hand the evaluation to `security` or
   `cost-finops` in one line — do not adjudicate it here.
7. MAKE IT DURABLE, AND KEEP THE REGISTRY CONSISTENT.
     - **Revisit trigger.** A revisit condition must be observable by someone who was not
       in the room: a threshold on a metric the system already emits, a date, a headcount,
       a volume, a named event. "When it becomes a problem", "if we outgrow it" and "at
       the next review" are not triggers. A trade-off without a trigger is a permanent
       accident.
     - **Durability.** The rationale must live in a versioned artifact next to the code —
       an ADR, a decision record, a design file in the repo — not in a PR description, a
       commit message body, or a chat link. If the only record of the choice is the diff
       itself, it is unrecorded. (Records-in-source-control is practitioner consensus,
       promoted on the Thoughtworks Technology Radar in 2018 and not re-assessed since;
       treat it as consensus, not evidence.)
     - **Graph integrity.** Before drafting anything, check whether this choice
       contradicts, narrows, or supersedes an **ACCEPTED** decision in the registry. If it
       does, the remedy is two records, not one: the new proposed decision *and* a status
       change marking the old one superseded, linked in both directions. Apply this only
       when the registry actually holds accepted records with module globs you can match —
       on an empty or unglobbed registry, say so and skip it rather than inventing
       contradictions.
     - Then close the loop: draft the chosen option as a PROPOSED decision —
       `tp decision new "<title>" --status proposed --alternative 'opt | gained | given up' --modules <globs> --req <R-id>`
       — for the human to accept. Proposing is this lens's job; accepting is the gate's.

**What this lens cannot see.** You are reading a diff plus injected context. You cannot
see the meeting, the whiteboard, the options someone considered and discarded before
typing, or anything a stakeholder knows and did not write down. Two consequences, binding:
an undeliberated choice can only be claimed when the *record* is absent, not when the
*thinking* is invisible — so every Blocker names the artifact you searched and found
nothing in; and set `confidence` mechanically — `high` only when the as-built inventory,
the registry and architecture's tradeoff points were all present and used, `medium` when
one is missing, `low` when two or more are.

**Close with the non-risks.** Report up to three significant choices you examined and
found sound as `praise`, one line of reasoning each. Recorded non-risks are how a decision
stops being re-litigated every cycle; the cap is what stops that becoming paperwork.

**Blocker** = a ONE-WAY-DOOR choice (check 3) with no alternative recorded in any durable artifact and no stated rationale; or a design that reinvents or contradicts a component in the as-built inventory; or a choice that contradicts an ACCEPTED decision without superseding it.
**Major** = a significant choice whose trade-off omits a real cost from the taxonomy in check 6, names no quality attribute being optimised, rests on a strawman alternative by the test in check 4, shows two or more of the reverse-engineering signals in check 5, has no observable revisit trigger, or is left unrecorded in the registry.
Minor = worth fixing, doesn't gate. Prefer the smallest suggestion that resolves each finding.

## How this lens runs

Apply this lens where it helps verify the requested outcome. Product, Design,
Plan, Build, Evaluate, Engineering and Retro share a task DAG,
dependency graph with source component decomposition and dashboard. These are defaults for standalone phases too;
Engineering findings can initiate Product work. Use native tools and host permissions.
Delegate only when authorized and useful. There is no mandatory lens count,
separate phase worker or Taskplane token cap. Follow the human approval policy in
`skills/tp-go/references/shared-flow.md`: every phase needs explicit human checkpoint
acceptance. Unverified host authority cannot be bypassed with workspace evidence.


## Shared review evidence

Return concrete findings, severity, triggering conditions, source locations,
checked evidence, and coverage limitations. Use `agents/tp-lens.md` and attach
this evidence to the existing run and review index. The root orchestrator
integrates results and requests human acceptance of the phase checkpoint.
Review findings do not grant write scope or approve delivery.