Reviewing Technical Design

reviewing-technical-design — SKILL.md

> Variant: standard · When to use: judging a finished technical design doc as an acceptance gate — checking an engineer can implement it without re-deriving the design, then emitting VERDICT: approve|revise with actionable findings. Greenfield, or an amend (delta-scoped).

Overview

This skill is the review half of a producing/judging technical-design pair. Loaded by a reviewer who holds a finished technical design document (TDD) — the document below the feature-spec that says how one feature will be built within an existing system — it judges that doc against one question: can an engineer implement this feature without re-deriving the design, and is the chosen approach justified against a real alternative? It applies a fixed 11-condition implementability checklist (the same bar a TDD author produces to — authoring-technical-design's Step-5 — so the produce-bar and the review-bar do not drift), then emits a single machine-parseable verdict plus findings the author can act on in one revision pass. It is an acceptance gate — it does not author, fix, or rewrite the design; it judges and returns findings, and the producer revises.

The bar is single-sourced with the author. The author's techniques — FMEA failure-mode analysis, the RTM trace matrix, C4 altitude framing, the choice of sequence vs flow diagram, pseudo-code form — are aids the reviewer judges by OUTCOME (is every decision traced? are failures handled? are signals named?), never conditions to demand. But note the boundary: rollout, observability, and testing ARE real, load-bearing conditions for a TDD (cond-7/8/9) — they are not "invented" conditions here the way a rollout demand would be for a feature-spec. What stays an aid is the technique (FMEA/RTM/C4/diagram-choice), not the outcome (a named signal, a traced decision, a rollback trigger).

When to activate

• A finished technical design doc needs an accept/revise decision before an engineer implements from it.
• You are the independent reviewer / gate for a TDD a producer just authored.
• Re-judging a revised TDD after a prior revise verdict.
• Reviewing an amend — an approved TDD + a change request — as a delta-scoped review (cond-11).

Do NOT activate when:

• Authoring or repairing a TDD → use authoring-technical-design. This skill never writes the design.
• Reviewing the upstream PRD or feature-spec (what/why; how each feature behaves) → use a PRD-review / feature-spec-review skill. This gate judges how the feature is built, one layer down.
• Reviewing the api-spec or data-model themselves (the wire contract / the persisted schema) → those are their own documents this TDD references, with their own gates.
• Reviewing a generic / ad-hoc engineering design doc, RFC, ADR, spec, or plan (one not produced as the doc-library technical-design artifact) → use design-review, which verifies design claims against the codebase across all those types. This gate is for the doc-library technical-design artifact — identified authoritatively by the template: technical-design frontmatter; a # Technical Design: heading is a fallback signal only when frontmatter is absent (a generic doc that merely titles itself "Technical Design" without the stamp stays with design-review).
• Checking template/section conformance → that is a template concern. This skill judges quality against the bar, not whether every heading is present.

Workflow

Step 1: Read the whole design with fresh, independent eyes

Read the TDD end to end as if encountering it for the first time, without the author's framing. Your stance is a gatekeeper for the next step (implementation): a finding carries weight only when it shows the feature cannot be built as designed without re-deriving something the design should have settled. Keep the upstream feature-spec + PRD (and the architecture-doc / api-spec / data-model the TDD references) at hand — Step 2's first condition checks the design against the requirements both ways, and cond-4 checks that referenced contracts are not duplicated. Is this an amend? If you were handed a change request / delta against an existing TDD, run the delta-scoped path (cond-11 active; scope the review to the changed decisions + their ripple). On a greenfield first build no change request is present — cond-11 is n/a.

Step 2: Run the implementability checklist — judge each condition

For each condition below, decide pass or gap. A condition fails only on a real, named deficiency — "I'd have designed it differently" is not a gap. For each gap, capture the exact location and what is missing (Step 4 turns it into an actionable finding). The conditions are the single-sourced bar; do not add private ones.

1. Requirement trace complete + bidirectional. Every requirement the feature must satisfy (PRD goal / feature-spec criterion / constraint) has a design element that satisfies it, and every non-trivial design decision traces back to a requirement — check both directions. A decision with no requirement is scope creep / gold-plating; a requirement with no design is a coverage gap. Gap on an orphan decision, an uncovered requirement, or unstated/unreconstructable traceability. (Non-collapsing baseline — at any size a decision serving no requirement is broken.)
2. Scoped to one feature / right altitude. The doc designs one feature/component within the existing architecture; system-wide structure is referenced, not redesigned. Gap when the TDD re-decides the topology / datastore / service boundaries (architecture work at the wrong altitude) instead of referencing the architecture-doc. (Non-collapsing baseline.)
3. Approach + decomposition implementable. A short approach overview; components/modules each with one responsibility + their collaborators, concrete enough to build; the primary control + data flow shown as a diagram AND a numbered narration that agree. Gap on a god-component, a box labelled only with the feature name, a flow with no diagram or a diagram that contradicts the prose. (Collapse: a small feature has few components and a short flow.)
4. Reference-not-duplicate (SSOT). Interfaces / schemas / topology an api-spec / data-model / architecture-doc already owns are referenced with only the delta stated — not inlined. Gap when the TDD pastes an endpoint list, a table DDL, or the service topology that an owning doc holds (guaranteed future drift). (Collapse: a feature touching no owned contract has nothing to reference — not a gap.)
5. ≥1 real alternative with a decision criterion. At least one genuine (non-strawman) alternative a competent engineer might have chosen, compared via trade-offs, with the decision criterion that settled the choice stated. Gap on a single rubber-stamped option, a strawman ("do nothing / rewrite everything"), or a choice settled by assertion ("we picked the best") with no criterion. (Non-collapsing baseline — the trade-off discipline holds at any size.)
6. Failure modes + cross-cutting robustness. The significant failures (bad input, dependency failure/timeout, partial failure) are enumerated, each with its detection + handling/recovery + user-visible effect; the concurrency / ordering / idempotency stance is named where relevant; the security / scale / privacy surface is addressed where the feature has one. Gap on a happy-path-only design, a failure listed with no handling, or an unaddressed security/data surface the feature clearly has. (Collapse: a thin feature has a smaller failure surface and may have no security/privacy/concurrency surface — fewer is fine; failure-carries-handling is itself a non-collapsing baseline.)
7. Observability addressed. The health + failure signals the feature emits/monitors are named (a success/error metric, the key log/trace, the alert on the dominant failure mode) — the signals that also arm the rollback triggers. Gap on "we'll add logging later" for a production-facing feature, or a rollback (cond-9) with no signal behind its trigger. (Collapse: a trivial internal helper keeps this brief — light is fine, absent-where-warranted is not.)
8. Testing addressed. The verification approach is stated in testable terms — the unit/integration/e2e levels appropriate to the feature, the failure cases from cond-6, and contract conformance for any contract the feature exposes; it references the feature-spec's acceptance criteria rather than restating them. Gap on "we'll test it", a strategy that omits the failure cases, or an exposed contract with no conformance check. (Collapse: a trivial feature may be unit-only; no exposed contract → no conformance check.)
9. Rollout / migration / rollback addressed. How it ships (phasing / feature-flag / canary); the migration + backward-compat stance where data/contract changes; a rollback plan with measurable triggers (tied to the cond-7 signals, not "roll back if it looks bad"). Gap on an implied big-bang for a risky change, a data/contract change with no migration, or a rollback with no measurable trigger. (Collapse: an internal additive feature has a trivial deploy and no migration — light is fine.)
10. Assumptions explicit + grounded, not fabricated. Genuine unknowns are surfaced as assumptions / open questions, not papered as settled fact; the design reflects this feature's specifics and the real surrounding system; no approach/limit/interface is invented to look complete. Gap when the design reads as falsely complete, or asserts a limit/interface/approach that appears fabricated (no upstream or research behind it). (Non-collapsing baseline.)
11. (Amend only) delta is well-scoped, ripple-clean, versioned. When reviewing a change against an existing TDD: the delta meets conditions 1–10 on the decisions it touched; the changed decision still traces to a requirement (or an upstream-PRD/feature-spec-amend-needed is explicitly flagged); the SSOT ripple is handled (if a contract changed, the owning api-spec/data-model amend + the downstream impl/test-plan/runbook re-point are named); the doc's own version is bumped + a changelog (who/when/what/why) present; superseded decisions are marked, not silently deleted. Gap on an un-scoped delta, a broken trace, an un-flagged SSOT ripple, missing change history, or a silent deletion. (Collapse: on a greenfield first build this condition is n/a — do NOT full-re-review an unchanged TDD, and do NOT demand a changelog on a first draft.)

Proportionality. "Implementable without re-deriving the design" scales with the feature. A thin feature legitimately collapses what it does not need — no concurrency → no concurrency stance; nothing persisted → no migration; trivial internal helper → light observability; no exposed contract → no conformance test; first draft → no changelog. Judge completeness-of-decisions, not word count or template-section presence. A small, complete design that satisfies every applicable condition passes. Do not manufacture a gap from brevity.

Step 3: Decide the verdict

• approve — every applicable condition passes. An engineer can implement this feature as designed, without re-deriving the design; the chosen approach is justified. Approve even if you can imagine stylistic improvements; the bar is implementability, not perfection.
• revise — one or more conditions have a real, named gap that blocks implementation (an orphan decision, a mis-scoped redesign, an inlined api-spec contract, a single un-weighed option, a failure with no handling, no observability on a production feature, a strategy missing the failure cases, a rollback with no measurable trigger, an un-scoped/ripple-broken amend, etc.).

Do not revise to signal effort or to request nice-to-haves. A condition is either met or it isn't.

Step 4: Emit the verdict + actionable findings

Emit the verdict as a single line — the literal text VERDICT: approve or VERDICT: revise, on its own line, with no surrounding code fences, quotes, or extra words (the fences here are illustration only):

VERDICT: approve

Then, on the following lines, list findings. On revise, every finding is actionable — the failed condition, the exact location, and how to fix it — so the author can resolve it in one pass. On approve, findings are optional non-blocking notes; do not let them imply a revision is required.

A good finding names the gap and the fix:

> revise — Reference-not-duplicate (cond. 4), §5 Interfaces: the full GET /reports endpoint list (params, response schema) is pasted from the api-spec. Fix: reference api-spec §Reports and state only this feature's delta (the new format=csv param), so the contract has one source of truth.

A bad finding is vague and unactionable:

> The interfaces section could be tightened up. (Which contract? Why does it fail the bar? What fixes it?)

Rules

Hard rules (never violate):

• Emit exactly one verdict line, VERDICT: approve or VERDICT: revise — that literal token, on its own line, nothing else on it. Downstream tooling parses it.
• Judge, never author. Return findings; do not rewrite, fix, or fill in the design. The producer revises.
• Single-sourced bar. Judge against the eleven conditions in Step 2 — the same bar the author (authoring-technical-design Step-5) produces to. Do not invent extra conditions or apply a stricter private standard.
• Aids are judged by outcome, never demanded. FMEA, the RTM matrix, C4 altitude language, the sequence-vs-flow diagram choice, pseudo-code form are the author's techniques — judge whether the decision is traced / the failure handled / the signal named, NEVER "you didn't use FMEA / draw an RTM / use a sequence diagram." (Rollout/observability/testing OUTCOMES are real conditions cond-7/8/9 — only the techniques are aids.)
• No false-revise. A design that meets every applicable condition is approved, even a thin one for a small feature. Revise only on a real, named gap. A thin feature legitimately omits migration, concurrency, a separate observability section, a changelog.
• No false-approve. Never approve over a genuine gap to be agreeable. A blocking gap is a revise.
• Failure without handling is a gap (cond. 6). The builder must not be left to invent the recovery.
• Reference-not-duplicate is load-bearing (cond. 4). An inlined contract another doc owns is a real gap (drift), not a style nit.
• Judge against the upstreams the document was given. Assess the TDD against its depends_on set + the docs it references. A not-produced upstream is never a revise trigger. A TDD that ignored a produced upstream it should have referenced is a fair finding.
• Amend is delta-scoped. When handed a change against an existing TDD, review the delta + its ripple (cond-11) — do NOT full-re-review the unchanged design, and do NOT demand a changelog on a greenfield first draft.
• Every revise finding is actionable — failed condition + location + concrete fix.

Preferences (override-able):

• Order findings by severity — blocking gaps first, then minor ones.
• Reference the condition number/name in each finding so the author maps it back to the bar.
• Keep approve-notes few and clearly non-blocking.

Gotchas

• Approving for completeness instead of buildability. Every section can be present and the feature still un-buildable (an ambiguous decomposition, failures with no handling, an inlined contract that will drift). Judge whether the feature can be implemented without re-deriving the design, not whether the template is filled.
• The listed-but-unhandled failure. A design that enumerates bad-input, timeout, and partial-failure looks thorough — but if it does not say *

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: bm629
• Source: bm629/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.