review-design · diff
git:20261025.e368b6b to git:20261025.9787473
3 added, 3 removed. Audit A to A.
---
name: review-design
description: |
Review design, implementation, and task documents produced by design. Evaluates document quality, internal consistency, and technical soundness.
Use after design completes and before starting implement.
---
# Design Review
## Conventions
- **Read capy knowledge base conventions** at [shared-capy-knowledge-protocol.md](shared-capy-knowledge-protocol.md).
- **Read verification policy** at [shared-verification-policy.md](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 three distinct dimensions
+ 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. One internal `design-reviewer` sub-agent plus external review chosen **once at discovery**: `pal codereview` (document-review branch) when an API model is available, otherwise one `pal clink` CLI review per eligible non-authoring provider using its configured model (variable count; on the clink roster the provider that authored the documents is excluded; PAL's shipped clients get default provider mappings that the report labels as assumed, and an operator declaration, for example in the project's `CLAUDE.md` or `AGENTS.md`, overrides them and is required for any other client name). Every reviewer applies the same shared design-review criteria and verification policy, framed as document review so planned implementation is not reported as missing code. Produces a report organized by agreement level with corroborated findings highlighted.
+ Delegates detection to independent reviewers that did not participate in the design, then annotates their findings with author context. One internal `design-reviewer` sub-agent plus external review chosen **once at discovery**: `pal codereview` (document-review branch) when an API model is available, otherwise one `pal clink` CLI review per eligible non-authoring provider using its configured model (variable count; on the clink roster the provider that authored the documents is excluded and each client's provider must be declared by the operator, for example in the project's `CLAUDE.md`). Every reviewer applies the same shared design-review criteria and verification policy, framed as document review so planned implementation is not reported as missing code. Produces a report organized by agreement level with corroborated findings highlighted.
- **Cost**: Higher (sub-agent + one or more external reviews + annotation); clink cost scales with the roster size
- **Isolation**: True — reviewers have zero authorship bias or session context; each external reviewer gets a fresh conversation
- **Degradation**: Graceful — a failed reviewer is disclosed and the others proceed; an API runtime failure never switches to clink; if every reviewer fails, suggests standard mode fallback
- - **Requires**: a PAL build whose `listmodels` exposes CLI client observations in every mode for the clink path; unresolved discovery keeps the internal review with an explicit external coverage limit. Operator setup (the minimum PAL build, CLI read access outside the project, provider declarations) is described in the plugin README under "Isolated reviews with external models"
+ - **Requires**: a PAL build whose `listmodels` exposes CLI client observations in every mode for the clink path; unresolved discovery keeps the internal review with an explicit external coverage limit
- **Scope**: the same default all-documents scope and explicit `design` / `implementation` / `tasks` subsets as standard mode; missing requested documents are disclosed, not substituted
- **Best for**: When extra rigor is worth the cost (before starting implementation of high-stakes features)
See [review-isolated.md](./review-isolated.md) for the isolated workflow; it replaces the standard-mode process file in that mode and is the only place that loads the isolated-only shared files (the design-review criteria, the PAL codereview protocol and the external-review protocol). Standard mode does not read them.
## 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](./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
```