/review-a-design

name: review-a-design
description: "Reviews whether a design is SOUND — solving the right problem, derived from its stated goals and constraints — and emits ranked, evidence-backed findings, not edits. Read when asked to 'review this design', 'is this design sound', 'pressure-test this proposal', 'do a design review', 'does this solve the right problem', 'poke holes in this spec', 'should we build this', or to critique a proposal / spec / ADR / architecture or product decision. Do NOT read when the user wants to AUTHOR one of these — routing a new proposal is frame-a-proposal, a spec is write-a-spec, a decision record is record-a-decision, a postmortem is write-a-postmortem. Do NOT read for code review of a diff, or to fact-check individual claims (that is a correctness pass, a different job)."
compatibility: "Any agent host with the OpenKnowledge MCP server configured. Installed project-local by `ok seed --pack software-lifecycle` (`ok-beta` for Beta)."
metadata:
  pack: "software-lifecycle"
  author: "Inkeep"
  repository: "https://github.com/inkeep/open-knowledge-skills"

Review a design — is it sound, not just complete

The platform `/open-knowledge` skill still governs every markdown operation here (reads via `exec`, writes via `write`/`edit`, links as plain relative markdown, MCP owns in-scope `.md`); this skill layers design-review craft on top of it.

**Three reviews are not the same review, and only one is this skill's job.**

• **Completeness review** asks: is every section filled in? (Are Drawbacks and Alternatives non-empty?)
• **Correctness review** asks: are the individual claims true? (Does the benchmark really say 40ms? Is that API deprecated?)
• **Soundness review** asks: *should this be built at all, and is this the design that follows from the stated goals and constraints?*

You are doing the third. A proposal can be complete and factually correct and still be the wrong design — solving a symptom, chosen before its goals, engaging only strawman alternatives. Completeness and correctness are cheap to check and someone else's pass. Say this to the user up front if there's any ambiguity about what kind of review they want, then do soundness.

You produce **findings, not edits.** The author decides what to change. Never rewrite the artifact under review unless explicitly asked.

---

Step 0: Identify the artifact and read it — and what it inherits

**HARD GATE: never review a design you have not read end to end, and never review it in isolation from the decisions it inherits.** A review of the first half is worse than no review — it spends the author's trust on partial understanding.

1. Identify the type. It is one of:

• a **proposal** (`proposals/NNNN-name.md` — Motivation / Design / Drawbacks / Alternatives / Unresolved questions),
• a **spec** (`specs/NNN-name/spec.md` — Goals / Non-goals / Design / Migration / Test plan, with a `parent_proposal:`),
• a **decision** (`decisions/NNNN-title.md` — Context / Decision / Consequences, with a `supersedes:` chain), or
• an **in-flight choice with no document yet** (the user is deciding in conversation). This is a valid target — see Step 1.

2. Read it whole: `exec("cat proposals/0003-feature.md")`. 3. Read what it depends on. A design is only as sound as the ground it stands on:

• the **parent proposal** a spec links via `parent_proposal:`, and any proposal a decision implements;
• the **decisions it assumes** — `exec("grep -rln <subsystem-keyword> decisions/")`, then `cat` the relevant ones. A design that contradicts an accepted ADR without noting it is a finding by itself.
• the **prior postmortems in the same subsystem** — `exec("ls -A postmortems/")` and `search({ query: "<subsystem> failure" })`. A postmortem names a failure mode; a design that reintroduces it is your highest-value catch.
• **sibling proposals/decisions** it supersedes or overlaps — follow the `supersedes:` chain both directions.

4. If the design references source code, read the code with the host's **native** tools (`Read`, `Grep`) — source is outside the knowledge base. In-scope markdown stays on `exec`/`search`.

Do not proceed until you can name the goal, the constraints, and the prior decisions this design sits on top of.

---

Step 1: Reconstruct the design's own argument — and show it back

Before you critique anything, state the design's argument in your own words: **the goal it serves, the constraints it accepts, and why this design follows from them.** Show it to the user before Step 2.

Why this gate exists:

• If you can reconstruct it cleanly, the author gets a free confirmation that the intended reader understood it — often the most useful thing a review returns.
• **If you cannot state the goal, the constraints, and why this design follows from them, the reviewable object does not exist yet — and that IS the finding.** Stop and report it: "I can't reconstruct why this design follows from its goals; here's where the chain breaks." Reviewing the surface of a design whose argument you can't state produces confident noise. Hand it back to the authoring skill to make the argument legible first.

For an in-flight choice with no document, this step is where you force the argument into words for the first time. Frequently the act of reconstruction resolves the question without a single lens.

---

Step 2: Run the soundness lenses

Pass the design through each lens below. A lens is a named question plus the failure it catches — run the ones that bite for this artifact, skip the ones that plainly don't, and add any that earn their place. Do not mechanically fill all nine; a review that says the same shallow thing nine times teaches nothing.

• **Problem lens** — *Is the stated problem the real problem, or a symptom of one upstream?* Whose problem is it, and what evidence says it hurts today (not hypothetically)? A design aimed at a symptom is unsound however elegant. Failure it catches: solving the wrong prob