git:20261025.9787473 to git:20261025.7dcde54

1 added, 1 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 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 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.

+ 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.

- **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

- **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

| ------ | -------- | ---------------------------------------------------------------------------------------- | -------------------------------- |

| **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

```