DecisionAnalysis

DecisionAnalysis makes the evidence and arithmetic behind a recommendation inspectable. Every criterion and value carries a dashed definition affordance, so the reviewer can check what a word meant before trusting the score beside it.

How it looks

When to use it

Use it when the reviewer must audit a recommendation across explicit criteria rather than take it on trust — a choice weighty enough that they should be able to disagree with your reasoning rather than only with your conclusion.

Mark it critical when the reviewer must settle it before work begins. That is accepted only while the analysis is proposed and choosable, because a settled or audited analysis asks the reviewer for nothing.

When not to use it

Do not use it for a question the reviewer can answer from the option titles, and do not add criteria to make a small decision look considered. A matrix that nobody would disagree with is ceremony.

Compared with

• Decision — reach for it when option-by-option considerations are enough and a matrix would be ceremony.
• QuickDecision — reach for it for a small question that needs no comparison at all.

Usage

<DecisionAnalysis question="Which store?" state="proposed" interaction="choose" scoring="weighted">
  <Criterion title="Reliability" impact="5">
    How safely the store preserves review state.
  </Criterion>
  <Option title="PostgreSQL" recommended>
    <Score criterion="Reliability" verdict="Strong" tone="good" score="5">
      Transactions preserve related state atomically.
    </Score>
  </Option>
  <Option title="SQLite">
    <Score criterion="Reliability" verdict="Good" tone="good" score="4">
      A local transaction protects each write.
    </Score>
  </Option>
  <Reversibility rating="somewhat-hard">Changing stores requires a data migration.</Reversibility>
</DecisionAnalysis>

Authoring

Attributes

Attribute	Type	Required	Behavior
question	string	Yes	The question the matrix answers.
state	"proposed" | "decided" | "deferred"	No	Defaults to proposed.
interaction	"audit" | "choose"	No	audit is the qualitative default; choose is valid only while proposed.
scoring	"weighted"	No	Adds 1–5 criterion impacts, 1–5 star scores, totals, and the calculation.
critical	bare boolean	No	Accepted only with state="proposed" and interaction="choose".

Children

Criterion, Details, Option, and Reversibility are valid directly in DecisionAnalysis; Score is valid directly in an Option.

Element	Attributes
Criterion	title (required), impact from 1 to 5 when scoring is weighted
Option	title (required), summary, recommended, chosen
Score	criterion, verdict (required), tone, score from 1 to 5 when scoring is weighted
Reversibility	rating (required); exactly one per analysis
Details	Optional; at most one

Every Criterion and Score needs one non-empty flow-level paragraph of at most one sentence — the dashed title or value reveals that definition. Keep the body on its own lines. Every option must score every criterion. A decided analysis marks exactly one option chosen.

The matrix supports seven or more criteria without changing its authoring shape.

Answering it

With interaction="choose" on a proposed analysis, the reader can select an option, confirm it, and later change or clear the answer, exactly as on the other decision cards.

Answer the plan’s decisions owns the recorded-answer behaviour.