agentsclimarketplace

Decision record

Skill event4u-app/agent-config/dist/agent-src/skills/decision-record

Use when choosing between alternatives with trade-offs — X-or-Y decisions or a weighted decision matrix / gewichtete Entscheidungsmatrix ('score my options'); ADR via `adr-create`.From its SKILL.md

Install
npx -y skills add event4u-app/agent-config --skill decision-record

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 19 stars19 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

10.7 KB, ~2.6k tokens by cl100k_base, as published. Nobody here has run it

decision-record

Shape the thinking behind an architectural decision: list the options, expose trade-offs, lock the chosen variant, and wire the supersession chain. Hands off to adr-create for file mechanics (numbering, index, frontmatter). This skill does not write the ADR file itself.

When to use

  • A team is about to commit to a non-trivial architectural choice and wants the trade-offs on paper first.
  • Two engineers disagree on an approach — surface the options and consequences before one wins by attrition.
  • A previous decision needs revisiting; the result must supersede: the older ADR with explicit rationale.
  • German triggers: "lass uns das festzurren", "Trade-off-Matrix", "welche Option ziehen wir?".

Do NOT use when:

  • The file mechanics are the entire ask (numbering, regenerating the index) — route directly to adr-create.
  • The decision is reversible and small (e.g. variable rename) — ADRs are for choices that constrain future work.
  • The user wants a feature plan, not a decision — route to the planning command instead.

Cognition cluster

  • Mental model 4 — Second-order thinking. Every decision unlocks some futures and locks out others; the consequences block names what becomes harder, not just what becomes easier. See docs/contracts/mental-models.md § 4.
  • Mental model 6 — Theory of constraints. A decision that does not move the binding constraint is theatre; if the trade-off matrix scores every option the same on the constraint that matters, the options are fungible — surface and stop. See mental-models.md § 6.
  • Mental model 10 — Reversible vs irreversible. Two-way doors get a one-page record; one-way doors get the full options + consequences + supersession chain. The reversibility row of the matrix decides which template fires. See mental-models.md § 10. Corollary — a shortcut through a one-way door is a decision, not a defer. The cheap-and-simple option is preferred where the choice can be walked back later. Where it cannot — a public API shape, a DB schema, a migration, a wire format, a published identifier — "we can simplify this later" is false, so it never ships as a deferred note; it lands here as a recorded decision with its consequences named. The one-way categories are enumerated so the call is not left to a judgement about what feels important.
  • Team context-spine slot. Read the team slot of the context-spine to capture who is bound by the decision (review groups, on-call rotation). Skip if the consumer project has not filled it; note in the record.

Procedure

1. State the decision in one sentence

"We need to decide X because Y." If you cannot, the decision is not ripe — surface that and stop.

2. Identify and enumerate options (≥ 2, usually ≤ 4)

Each option gets:

  • Name — short, descriptive, never "option A / B / C".
  • Sketch — what it actually does in one paragraph.
  • Cost / benefit — three to five bullets per side, concrete.
  • Reversibility — easy / costly / one-way (Bezos two-way / one-way door framing).

Add an explicit "do nothing" option whenever it is plausible — forces the user to compare the change against the status quo.

3. Build the trade-off matrix

CriterionOption 1Option 2...
Implementation cost
Operational cost
Reversibility
Blast radius
Time-to-value

Pick criteria that separate the options. Criteria where every option scores the same are noise — drop them.

4. Lock the choice + consequences

Write:

  • Decision: "We pick <Option name>."
  • Consequences: what becomes true, what becomes harder, what becomes impossible. At least one of each, or admit that nothing becomes harder (rare; verify).
  • Revisit-if: the condition that would reopen this decision — new evidence class, a changed constraint the decision assumed, or an age threshold. A lock recorded without this line reads as permanent law instead of a decision under current conditions; see decision-revisit-gate for what happens when a later change is blocked by it without one.

5. Wire the supersession chain (if any)

If this decision overrides a prior ADR:

  • Cite the prior ADR id and one-line summary.
  • State what changed in the world that justifies overriding — not "we now think differently".
  • Hand off the supersedes: linkage to adr-create.

6. Hand off to file mechanics

Output the structured payload (below). The user — or adr-create — turns it into the file.

Weighted-matrix mode (quantitative)

Optional numeric variant of step 3. Gate — fire only when ALL hold: ≥ 3 options · no single dominant criterion · costly / hard-to-reverse decision · commensurable criteria (no values conflict). A 2-option or reversible choice gets a one-line redirect: just decide, or use the qualitative matrix above. Full procedure, anchors, worked example: references/weighted-matrix.md.

  1. User states the decision + options.
  2. User lists criteria and weights (1-10) BEFORE any scoring — the AI may append missed criteria afterward, each labeled (AI-suggested). Never propose criteria first (anchoring).
  3. Criteria hygiene: cap 4-8, merge near-synonyms (double-counting check).
  4. Score options 1-10 against fixed anchors (each criterion declares what 1 and what 10 mean — never relative-to-best-in-set).
  5. Weighted sums, then the sensitivity block — the load-bearing gate: close-call margin (< 10 % = "no clear winner — decide on unquantified factors"), smallest weight change that flips the winner, ±1-score flip test. A fragile winner is reported as fragile, never as "the rational choice".
  6. Delegate the argue-against pass to adversarial-review, scoped: "attack the winner, using the losing options' strongest criteria" (the premortem delegation pattern — never reimplemented inline).

Output appends matrix + sensitivity block + attack summary + the intuition caveat (resistance to the result signals a wrong weight or unquantified information — surface it, don't ignore it). The score is a structured argument, not a verdict. Hand-off to adr-create is unchanged.

Related Skills

WHEN to use this

  • The team is about to lock a non-trivial choice and the trade-offs need to survive the conversation that produced them.
  • A prior ADR is being overridden and the supersession chain needs explicit "what changed in the world" rationale.
  • A planning thread has surfaced ≥ 2 viable options and silence is about to pick one by attrition.

WHEN NOT to use this

  • The choice splits stakeholders along role lines (PO vs ops, eng vs support) — start with stakeholder-tradeoff; this skill locks the choice after the human cost is mapped.
  • The output is the ADR file itself (numbering, index regen) — route to adr-create; this skill produces the payload, not the file.
  • The risk shape is the dominant question — route to risk-officer first, then return.
  • MANY items to rank on the fixed R×I×C/E formula (backlog, feature list) — route to rice-prioritization; the weighted-matrix mode here is for ONE choice on custom criteria.
  • The decision is reversible and cheap — write a one-line note and move on; ADRs are for irreversible or expensive constraints.

When the agent should load this

  • "Lass uns das festzurren."
  • "Welche Option ziehen wir und warum?"
  • "Wir müssen ein ADR draus machen."
  • "Trade-off-Matrix für X vs Y."
  • "Diese Entscheidung überschreibt das alte ADR-NN."
  • "Weighted decision matrix für die Optionen" / "score my options against my criteria" — fires the weighted-matrix mode (gate permitting).

Output

Decision: <one sentence>

Options:
  1. <name> — <sketch>
       Pros: ...
       Cons: ...
       Reversibility: easy | costly | one-way
  2. ...
  N. Do nothing — <sketch>

Trade-off matrix:
  | Criterion | <opt 1> | <opt 2> | ... |
  | ...

Locked: <chosen option name>

Consequences:
  + <becomes true>
  - <becomes harder>
  ✗ <becomes impossible>

Supersedes: <ADR-XYZ "title">  (if any)
Trigger:    <what changed>     (if superseding)

Next: /adr-create  with the payload above

Gotcha

  • "We compared the options" is not a comparison. The matrix must separate them on at least two criteria.
  • Pros without cons is advocacy, not analysis. If you cannot find cons for the chosen option, you have not understood it yet.
  • A supersession with no "what changed in the world" is a vibe pivot. Reject and ask.

Do NOT

  • Do NOT pick the option before listing them — the matrix is the point, not the conclusion.
  • Do NOT write the ADR file from this skill — adr-create owns filenames, numbering, and index regeneration.
  • Do NOT pad option counts to look thorough; two real options beat four straw men.
  • Do NOT silently update an old ADR; supersession is explicit.

Runnable example

Replacing the in-house cron runner with a managed scheduler:

  • Decision: "We need to decide between keeping the in-house cron runner and migrating to the managed scheduler because the on-call rotation has paged on missed-run incidents three times in 60 days."
  • Options: (1) keep in-house + add monitoring; (2) migrate to managed scheduler; (3) do nothing.
  • Matrix rows that separate options: implementation cost, operational load, blast radius on outage, reversibility.
  • Locked: "We pick the managed scheduler."
  • Consequences: + on-call gets paged on scheduler infra, not application code. – job definitions move to a vendor format, raising migration cost if we leave. ✗ we cannot run jobs in the app process anymore — assumes vendor uptime.
  • Supersedes: ADR-014 "in-house cron runner"; trigger = three missed-run pages in 60 days now exceed the SLO budget.
  • Next: /adr-create with the payload, append supersedes: ADR-014.

What ships with it: 3 files

9.0 KB alongside SKILL.md

evals/

references/

Keep looking

Skills are one crate of 610,677. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.