review-design

Review design, implementation, and task documents produced by design. Evaluates document quality, internal consistency, and technical soundness. Use after design completes and before starting implemen

SKILL.md

GitHub

Design Review

Conventions

Overview

Pre-implementation review gate that evaluates design documents produced by /kk:design before code is written. Sits between /kk:design (creates docs) and /kk:implement (executes them). Reviews tree distinct dimensions

  • document quality/structure (completeness, internal consistency, clarity, convention adherence)
  • technical soundness (architectural viability, edge cases, failure modes, trade-off analysis)
  • feature value (Does the feature improve things for end-users? Is it useful? Is it correct in how it tries to solve the problem?)

Review Modes

Standard Mode (/kk:review-design)

Reviews design documents in the main conversation context. Fast, single-pass review using the workflow below.

Isolated Mode (/kk:review-design:isolated)

Delegates detection to independent reviewers that did not participate in the design, then annotates their findings with author context. Two parallel reviewers: a design-reviewer sub-agent and pal codereview (external model in native format). Produces a report organized by agreement level with corroborated findings highlighted.

  • Cost: Higher (sub-agent + external model + annotation)
  • Isolation: True — reviewers have zero authorship bias or session context
  • Degradation: Graceful — if one reviewer fails, proceeds with the other; if both fail, suggests standard mode fallback
  • Best for: When extra rigor is worth the cost (before starting implementation of high-stakes features)

See review-isolated.md for the isolated workflow.

Finding Types

Type Code Description
Incomplete Spec INCOMPLETE Section lacks sufficient detail for implementation
Internal Inconsistency INCONSISTENT Two parts of the docs contradict each other
Technical Risk TECH_RISK Architecture choice has unaddressed failure modes, scalability concerns, or edge cases
Missing Concern MISSING Cross-cutting concern is absent (error handling, migration, backwards compatibility)
Ambiguity AMBIGUOUS Requirements can be interpreted multiple ways, likely to cause implementation divergence
Structure Issue STRUCTURE Document doesn't follow project conventions — missing sections, vague subtasks

Severity Levels

Level Name Description Action
P0 Critical Fundamental flaw — design will not work as described, or critical requirement is missing Must fix before implementation
P1 High Significant gap — likely to cause rework or wrong implementation Should fix before implementation
P2 Medium Moderate concern — ambiguity or missing detail that could cause confusion Fix or create follow-up
P3 Low Minor — style, structure, or nitpick Optional

Workflow

Mandatory order — methodology before evaluation. The flow below is strictly sequential. Load this SKILL.md, the selected process file and shared protocols before reading or evaluating subject documents. Only bounded inspection for a declared routing predicate may precede remaining instruction loads. The review methodology and rubric precede the design documents they assess.

Phases:

  1. Load documents — parse scope, locate feature directory, read in-scope docs
  2. Capy search — search kk:arch-decisions and kk:review-findings for prior context
  3. Document quality review — completeness, clarity, consistency, convention adherence
  4. Technical soundness review — viability, edge cases, trade-offs, scalability, testing strategy
  5. Self-check and confidence assessment — re-read, question assumptions, assign confidence
  6. Present findings with next steps

See review-process.md for the detailed step-by-step process.

Invocation

Post-design gate. This is the recommended review step after /kk:design completes and before /kk:implement begins. The default scope reviews all documents, including task-format checks.

Standard mode — reviews all documents by default:

/kk:review-design [feature-name]

Standard mode with scope — review specific documents:

/kk:review-design [feature-name] design
/kk:review-design [feature-name] implementation
/kk:review-design [feature-name] tasks
Scope Documents reviewed
(none) design.md + implementation.md + tasks.md
design design.md only
implementation implementation.md only
tasks tasks.md only

Isolated mode with independent sub-agents:

/kk:review-design:isolated [feature-name]
/kk:review-design:isolated [feature-name] tasks