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.mdklaude-plugin/skills/review-design/SKILL.md
GitHubDesign Review
Conventions
- Read capy knowledge base conventions at shared-capy-knowledge-protocol.md.
- Read verification policy at shared-verification-policy.md.
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:
- Load documents — parse scope, locate feature directory, read in-scope docs
- Capy search — search
kk:arch-decisionsandkk:review-findingsfor prior context - Document quality review — completeness, clarity, consistency, convention adherence
- Technical soundness review — viability, edge cases, trade-offs, scalability, testing strategy
- Self-check and confidence assessment — re-read, question assumptions, assign confidence
- 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