review-a-design

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.