decision-review

decision-review

Audit a past architectural decision: restate what was chosen and why, compare the original assumptions against reality now, and produce a verdict (still valid / needs amendment / superseded). Ends with a historical-patterns memory candidate per the Analysis Memory Loop.

Direction: backward (did it hold?) not forward (which option?). For forward flow, use decision-record. For filing the ADR file, use adr-create.

When to use

• Revisiting a past architectural decision: "Did ADR-042 still make sense given what we learned?"
• A prior ADR is being cited as precedent and its validity should be checked before relying on it.
• A post-mortem or retrospective surfaces that an earlier choice may have contributed to problems.
• Preparation for a supersession: confirm the old decision actually needs replacing before writing a new ADR.
• Routed here by decision-revisit-gate when a beneficial change is blocked by a recorded lock (honest-null verdict, "don't relitigate" memory, budget canon, or ADR) — this skill supplies the backward-audit procedure that rule's re-evaluation offer points to.

Do NOT use when:

• Making or locking a new decision — use decision-record (which builds the options matrix and locks the choice).
• The ask is to file or number the ADR file — use adr-create.
• No prior decision or ADR exists to review — nothing to audit.

Procedure

1. Locate and inspect the decision

Identify the ADR in docs/decisions/ (flat, ADR-NNN-<slug>.md) or docs/adrs/<area>/ (per-area, NNNN-<slug>.md), or a logged decision in agents/decisions/. If the user named the decision informally, check the index for the slug before reading. Read the full file before proceeding.

2. Restate: what was decided and why

Extract and restate in your own words:

• Chosen option — what was picked.
• Context then — the forcing function that made the decision necessary.
• Assumptions — the explicit and implicit priors the decision rested on (load, team size, vendor stability, regulatory state, tech maturity, cost, etc.).
• Alternatives rejected — why each runner-up lost.

This restatement is the baseline. Later steps compare against it.

3. Compare to reality now

For each assumption identified in step 2, classify:

Also list new information that did not exist when the decision was made (new tooling, changed requirements, post-mortem learnings, usage data).

Hindsight discipline: judge each assumption against the information available at the time it was made, not against the outcome alone. A decision can be correct given the information then and still need revision now.

4. Verdict

One of three:

• Still valid — assumptions largely held; no amendment needed. Document the validation date so future reviewers know it was checked.
• Needs amendment — core decision stands but one or more consequences or constraints must be updated. Recommend the specific amendment and suggest filing a narrow ADR or addendum.
• Superseded — the chosen option no longer serves the original goal or a new forcing function invalidates it. Name the successor option. Recommend handing off to decision-record (to lock the new choice) then adr-create (to file the superseding ADR with supersedes: ADR-NNN).

5. Memory write-back (dedup-first)

Before drafting a new candidate, call retrieve() over the same key-space (decision area, affected paths):

• Match found — propose a frequency / supersedes update to the existing entry. Do not create a duplicate.
• No match — draft a new historical-patterns candidate per the Analysis Memory Loop § 1:

{
  "type": "historical-patterns",
  "summary": "<one-line pattern: what held or broke>",
  "evidence_paths": ["docs/decisions/ADR-NNN-<slug>.md"],
  "decision_surface": ["<area1>", "<area2>"],
  "last_validated": "YYYY-MM-DD",
  "review_after_days": 90,
  "applicable_scope": "project"
}

Surface the draft to the user via /memory propose. Never auto-promote. If the candidate fails the admission gate (< 2 distinct evidence paths AND < 3 future decisions in decision_surface), surface the gap and suggest deferring or strengthening evidence.

Output

1. Decision restatement — chosen option, context then, assumptions, alternatives rejected.
2. Assumption-drift table — each assumption: held / broke / unknown, with evidence.
3. New information not available at decision time.
4. Verdict — still valid / needs amendment / superseded — with rationale.
5. (optional) Memory candidate — historical-patterns draft or update proposal.

Do NOT

• Re-litigate a decision that the verdict confirms is still valid. Acknowledge it, note the validation date, stop.
• Duplicate decision-record's options matrix and trade-off table — this skill reads the old matrix; it does not rebuild one unless the verdict is "superseded" and a new decision process is needed.
• Auto-promote memory candidates — the human drives promotion per the Analysis Memory Loop.
• Issue a "superseded" verdict without naming the successor option or recommending the forward path to decision-record + adr-create.

Gotchas

• Backward vs forward: decision-review asks "did the chosen option hold up?" — decision-record asks "which option should we pick?" Conflating them produces a partial analysis: either a verdict without a replacement plan, or a replacement plan without understanding what broke.
• Hindsight bias: a decision made with the information available then can be correct even if the outcome was poor. State what was known at the time; avoid framing a correct past decision as wrong because newer facts exist.
• Stale memory entries: if retrieve() returns entries in skipped (stale — age > review_after_days), surface them to the user; do not silently use stale entries as if they were current.

Decision-revisit gate — mechanics (migrated from the decision-revisit-gate rule)

Body of decision-revisit-gate (per P4 of road-to-kernel-and-router.md). The Iron Law — benefit blocked by a lock → surface + offer re-evaluation, never silent compliance — stays in the rule; the lock catalog, fire steps, and failure modes live here.

What counts as a "lock"

• An eval verdict recorded as an honest null (a mechanism was tested, showed no lift, and the disposition says "don't rebuild without new evidence").
• A memory entry or agents/settings/contexts/ note tagged "don't relitigate" / "settled" / a locked council convergence.
• A budget or frugality-canon line (token-budget-discipline, telegraph-speak, thin-projector trimming) that rejects a change on cost grounds alone.
• An ADR whose decision is being cited as a blocker for the current change.
• A hard structural cap (kernel size, per-domain persona cap, rich-skill ratio). A change that genuinely qualifies to cross the cap — e.g. a new rule that truly meets the kernel-membership inclusion criteria — triggers a cap-raise proposal + maintainer/council approval, never a silent downgrade of the rule to fit the old number (e.g. demoting a must-always-fire rule to auto just because the kernel says 9). Fitting the cap is not a reason to weaken a qualifying rule; but a rule that does not meet the criteria stays out — the cap is not the reason, the criteria are.

What to do when it fires

1. Mechanism-match check — do this FIRST. A verdict settles the mechanism it tested, not every future proposal that resembles it. Before applying the lock, verify the blocked change is actually the same mechanism — not merely a similar-sounding one. A null on hardened blocking enforcement does not automatically cover discretionary contextual nudges; a null on one architecture does not cover a materially different one. If the mechanism differs, the lock does not apply — proceed, noting the distinction.
2. If the mechanism genuinely matches, do not silently comply. Surface, in one short block:
   • What change is blocked.
   • Which lock blocks it (cite the memory/context/ADR).
   • Under what conditions the lock was recorded (date, evidence, or "maintainer decision" if settled-by-decision rather than settled-by-evidence).
   • What has changed since (new evidence, new model generation, new tooling, repeated encounters) that makes revisiting worth the cost.
3. Offer numbered options (per user-interaction), always including: re-evaluate the lock in the AI council. Other options: keep the lock as-is, or proceed without the blocked change.
4. On re-evaluation: run this skill's Procedure above for the backward audit and route to ai-council for the debate mechanics. The rule owns the obligation to surface; this skill and the council own the procedure.
5. Record the outcome with scope + revisit-if per ai-council's convergence-summary contract — every re-evaluated lock gets a fresh, correctly-scoped disposition, not a re-statement of the old one.

When NOT to fire

• The blocked change has no real benefit — the gate is not a lever to reopen every settled question; no-cheap-questions still governs whether the resulting numbered-options block is a real question or noise. A revisit-offer with a genuine trade-off is never a "cheap question" under that rule — but a revisit-offer with no actual case for change is.
• The mechanism-match check (step 1) shows the lock is the same mechanism and no new evidence exists — apply the lock, no surfacing needed; this is the lock working as intended.
• The user already declined a revisit on this exact lock this conversation — per scope-control § Decline = silence, do not re-ask.

Failure modes

• Treating a "don't relitigate" memory as permanently closed instead of as settled-under-conditions-X.
• Applying a null verdict to a superficially similar but architecturally different mechanism without running the mechanism-match check.
• Letting the token-frugality canon auto-reject a net-positive change without surfacing the trade-off — see token-budget-discipline's value-over-budget clause.
• Silently dropping a good idea because "we already decided this" — the canonical failure the gate exists to stop.

See also

• decision-revisit-gate — the rule whose migrated mechanics live above.
• decision-record — forward flow: lock a new choice.
• adr-create — file the ADR after a decision is locked.
• blameless-post-mortem — incident review; may hand off to decision-review when a prior architectural choice is implicated.
• docs/contracts/analysis-memory-loop.md — produce → propose → promote → retrieve contract.