decision-review · diff
git:20260706.1548aca to git:20260712.94dc19c
86 added, 0 removed. Audit A to A.
---
model_tier: high
name: decision-review
description: "Use to audit a past architectural decision — did the chosen option hold up, what assumptions drifted, should the ADR be superseded? Backward review only; does not lock new choices."
domain: process
workspaces:
- engineering
packs:
- analysis-workbench
trust:
level: professional
confidence: medium
install:
default: false
removable: true
---
# 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](../../../docs/contracts/analysis-memory-loop.md).
>
> **Direction:** backward (did it hold?) not forward (which option?).
> For forward flow, use [`decision-record`](../decision-record/SKILL.md).
> For filing the ADR file, use [`adr-create`](../adr-create/SKILL.md).
## 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`](../../rules/decision-revisit-gate.md)
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`](../decision-record/SKILL.md) (which builds the
options matrix and locks the choice).
- The ask is to file or number the ADR file — use
[`adr-create`](../adr-create/SKILL.md).
- 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:
| Assumption | Status | Evidence |
|---|---|---|
| *e.g. "vendor X is stable"* | held / broke / unknown | *e.g. "vendor deprecated API in v3"* |
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`](../decision-record/SKILL.md) (to lock the new
choice) then [`adr-create`](../adr-create/SKILL.md) (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](../../../docs/contracts/analysis-memory-loop.md):
```jsonc
{
"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`](../decision-record/SKILL.md)'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](../../../docs/contracts/analysis-memory-loop.md).
- 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`](../../rules/decision-revisit-gate.md)
+ (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`](../../rules/user-interaction.md)),
+ 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`](../ai-council/SKILL.md)
+ 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`](../ai-council/SKILL.md)'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`](../../rules/no-cheap-questions.md)
+ 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`](../../rules/scope-control.md),
+ 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`](../../rules/token-budget-discipline.md)'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`](../../rules/decision-revisit-gate.md) — the rule whose migrated mechanics live above.
- [`decision-record`](../decision-record/SKILL.md) — forward flow: lock a new choice.
- [`adr-create`](../adr-create/SKILL.md) — file the ADR after a decision is locked.
- [`blameless-post-mortem`](../blameless-post-mortem/SKILL.md) — incident review; may hand off to decision-review when a prior architectural choice is implicated.
- [`docs/contracts/analysis-memory-loop.md`](../../../docs/contracts/analysis-memory-loop.md) — produce → propose → promote → retrieve contract.