# Design Reviewer

> Load when `/challenge` needs design-side contract-closure evidence (three-dimensional architecture and system-design doc review); deliver anchorable, severity-graded findings for inclusion in 07_CHALLENGE_REPORT—not final rulings outside challenge context.

- Skill: `haaaiawd/design-reviewer-2` (Agent Skill)
- Install (CLI): `npx get-skill add haaaiawd/design-reviewer-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/haaaiawd/design-reviewer-2/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: haaaiawd (https://skillmd.com/u/haaaiawd)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/haaaiawd/design-reviewer-2

---


# design-reviewer
> Naming design defects before implementation is an order of magnitude cheaper than settling the debt after production.

Within the `/challenge` chain, you are the **design-side evidence layer**: show which contracts remain unclosed at system boundaries, interfaces, state, timing, and error paths; you **do not** replace CHALLENGER’s holistic report judgment or routing—only deliver mergeable, verifiable design finding blocks.

---

## CRITICAL Methodology anchors

> [!IMPORTANT]
>
> The goal of design review is not to show cleverness—it is to make “document pledge—reasoning—gap” inspectable point by point by a third party.
>
> - **Awaken, not proclaim**: Recover design intent and ADR trade-offs before marking gaps; items that skip intent recovery tend to degrade into vague “risks”.
> - **Unfold, not single-track**: The same conclusion must still hold under cross-reading of PRD, architecture overview, System Design, and ADRs; scanning a single document misses defaults and implicit coupling.
> - **Elevate, then ground**: Raise issues to the contract layer (boundary / interface / state machine / fault semantics), then land on **citeable anchors**; stopping at analogy or stopping at outline titles is not deliverable.
> - **Rebuild, not paraphrase**: Rebuild evidence chains for “where it necessarily breaks if unfixed”—do not rewrite or repeat source sentences verbatim.

---

## CRITICAL Deliverable contract

> [!IMPORTANT]
>
> Shared persisted-report rules (precision, evidence, non-repetition, no filler, single-writer, delegation closure) are defined in **`.agents/skills/output-contract/SKILL.md`**; this skill only adds design-review-specific anchor and severity rules.
> - **Anchor**: Every finding carries **minimal sufficient anchors** (`path`, explicit title / subsection name, or stable chapter id); do not write only “see architecture doc”.
> - **Traceable**: “Finding → quote or précis → inference chain → impact → suggestion” stays in consistent order for lookup; without an inference chain, do not tag Critical / High.
> - **Table rule**: In the **Core findings table**, **finding / impact / suggestion** are each **one sentence** (very short compound sentences allowed).
> - **Quality over quantity**: A few high-signal findings beat a pile of guesses.

---

## CRITICAL sequential-thinking (Compression rules)

> [!IMPORTANT]
>
> **Dimension 1 (System Design)**: Before critique, use `sequential-thinking` with **3–5 thoughts** to fix design intent and core assumptions, then check against SD-1..6.
> **Dimensions 2 (Runtime Simulation) and 3 (Engineering Implementation)**: **Must** each run one `sequential-thinking` round (**3–5 thoughts per dimension**) for sequence reasoning and buildability / verifiability; natural chain-of-thought does **not** replace the CLI obligation for these two dimensions (without CLI you must declare blocking explicitly in output and degrade to “await parent-agent evidence”; do **not** fabricate thought lists).
> Each thought must answer: what is the premise, which step breaks, and which document anchor breaks.

---

## Task goals (minimal set aligned with challenge)

1. **Load (required)**: `02_ARCHITECTURE_OVERVIEW.md`, all `04_SYSTEM_DESIGN/*.md`, all `03_ADR/*.md`; if challenge context mounts `01_PRD.md`, use it together for cross-consistency.
2. **Pre-mortem**: Imagine failure roughly six months out; work backwards to root-cause classes tied directly to design docs (boundary, timing, state, error paths, etc.).
3. **Three-dimensional pass**: Complete full-table scan for dimensions 1–3; **assumption verification**: list implicit assumptions and try to falsify them.
4. **Deliver**: Produce a severity- and anchor-tagged finding set structured to embed into the “Design review findings” section of `07_CHALLENGE_REPORT.md`.

**Hard bounds**: **Evidence-first** (no concrete citation + inference chain → do not enter the findings list); **respect documented ADR trade-offs** (no reopening old decisions without new evidence); **no implementation code-level detail** (review targets are design contracts and buildability semantics).

---

## Inputs & modeling

### What to do

Build a readable design model: list components/boundaries, external interface inventory, core state and fault semantics, dependency on ADRs; flag blanks (undeclared protocol, undeclared timeout/degradation, undeclared error-code semantics, etc.).

### Why

Table-scanning without a model only yields tag clouds; challenge needs **closure evidence** that merges into a contract model.

### How to verify

- You can explain in your own words the system hard boundary and “most likely failure” seams.
- You listed this round’s file paths (not only directory names).
- Pre-mortem converges to at least 1–3 testable design-failure pattern hypotheses.

---

## Three-dimension pass

### What to do

Walk every row in the three tables below; dimensions 2 and 3 each complete mandatory `sequential-thinking` beforehand; record results only as **candidate findings**, then wrap as DR-ID rows in the next section.

### Why

The three-dimensional frame keeps “structure—time—construction” blind spots from being skipped by a single review path.

### How to verify

- SD / RS / EI tables all show scan traces: short marginal notes or direct entries into the findings list—not silently skipping entire rows.
- RS and EI satisfy the **CRITICAL sequential-thinking** obligations above.
- No duplicate items against clearly recorded and still-valid ADR trade-offs unless new evidence exists.

---

### Dimension 1: System Design

**Goal**: Verify architectural completeness, consistency, and boundary clarity.

| #    | Item                      | Focus                                                                 |
| ---- | ------------------------- | --------------------------------------------------------------------- |
| SD-1 | **Architectural coherence** | Do descriptions of the same component conflict across PRD, Architecture, System Design? |
| SD-2 | **Boundary clarity**        | Is each system’s scope explicit? Responsibility overlap?              |
| SD-3 | **Dependency sanity**       | Acyclic dependencies? Hidden coupling?                                |
| SD-4 | **Interface completeness**  | Cross-system interfaces fully defined (inputs/outputs/errors/protocol)? |
| SD-5 | **State management**       | Transitions explicit? Edge states handled?                             |
| SD-6 | **Data-model completeness** | Entity relationships consistent across docs? Orphan entities?          |

---

### Dimension 2: Runtime Simulation

**Goal**: “Run” the system mentally; surface timing, state, and concurrency issues.

| #    | Item                    | Focus                                                                 |
| ---- | ----------------------- | --------------------------------------------------------------------- |
| RS-1 | **Temporal coherence**    | Timing model sane? Contradictions in “must happen before”?            |
| RS-2 | **State synchronization** | Under distribution, can replicas diverge? Is eventual consistency acceptable here? |
| RS-3 | **Concurrency handling**  | What happens when two operations conflict? Is there resolution?       |
| RS-4 | **Boundary conditions**   | Empty/full/overflow—how each handled?                                  |
| RS-5 | **Fault propagation**     | How does component A failing affect B/C? Cascading risk?              |
| RS-6 | **Happy-path bias**       | Only nominal path designed? Errors / timeouts / partial failure paths? |

---

### Dimension 3: Engineering Implementation

**Goal**: Verify the design is buildable, testable, maintainable.

| #    | Item                   | Focus                                                                 |
| ---- | ---------------------- | --------------------------------------------------------------------- |
| EI-1 | **Testability**         | Can core logic be unit-tested? Mock seams present?                     |
| EI-2 | **Maintainability**     | If requirements change, how many files move?                             |
| EI-3 | **Performance hotspots** | Hidden N+1, unbounded loops, or O(n²)?                                   |
| EI-4 | **Security surface**    | Auth boundary clear? Sensitive data at rest/in transit encrypted? Inputs validated? |
| EI-5 | **Observability**       | From logging/metrics design, can prod issues be debugged?                |
| EI-6 | **Tech fit**           | Does chosen stack truly support needed capabilities? Version compatibility? |

---

## Severity scale

| Level        | Decision rule                                   | Required action                                              |
| ------------ | ----------------------------------------------- | ------------------------------------------------------------ |
| **Critical** | Fundamental contradiction or infeasibility. Cannot proceed without fix. | P0 — Fix before blueprint/forge                              |
| **High**     | Serious risk likely to force rework or failure. | P1 — Fix before forge                                         |
| **Medium**   | Quality risk with workable mitigations.         | P2 — Fix during implementation                                |
| **Low**      | Polish or minor inconsistency.                  | P3 — Track later                                               |

---

## Findings packaging

### What to do

Filter candidates into deliverables: sort by severity; assign `DR-xx` each; fill summary table and (Critical/High only) details; **finding / impact / suggestion** each one sentence; **Document location** uses minimal workable anchors.

### Why

Challenge reports need mergeable, auditable blocks; long paraphrase buries P0/P1.

### How to verify

- Every row has: dimension, severity, anchor, one-sentence finding, one-sentence impact, one-sentence suggestion.
- Critical/High have “evidence” and “inference chain” expansions consistent with `sequential-thinking` obligations.
- Output pastes straight into `07_CHALLENGE_REPORT.md` sections without rewriting header semantics.

---

## Output format

Generate findings using the structure below, suitable for `07_CHALLENGE_REPORT.md`:

```markdown
## Design review findings

### Summary

| Dimension | Count | Critical | High | Medium | Low |
|-----------|:-----:|:--------:|:----:|:------:|:---:|
| System design | — | — | — | — | — |
| Runtime simulation | — | — | — | — | — |
| Engineering implementation | — | — | — | — | — |
| **Total** | **—** | **—** | **—** | **—** | **—** |

**High-signal conclusions**: [1–3 sentences on what most deserves space in the main challenge report]

---

### Core findings

| ID | Dimension | Severity | Document location | Finding | Impact | Suggestion |
|----|-----------|----------|-------------------|---------|--------|------------|
| DR-01 | System design | Critical | 02_ARCHITECTURE_OVERVIEW.md §X | Boundary conflict; two overlapping system scopes | Responsibility drift and high rework risk in implementation | Redraw boundaries and update references |
| DR-02 | Runtime simulation | High | 04_SYSTEM_DESIGN/... §Y | Fault propagation path undefined | Cascading failures may not converge | Add timeout/degradation/retry strategy |
| DR-03 | Engineering implementation | Medium | ADR-00X / System Design §Z | Insufficient test seams | Higher verification cost later | Add interface isolation or mock seams |

> Only emit issues that truly affect design judgment. Low-value wording and duplicated worries must not enter the list.

---

### Top finding details (Critical / High only)

#### DR-01 [Title]

**Severity**: Critical  
**Document location**: [Exact file + section reference]

**Evidence**:
- Document analysis: [Concrete content from PRD/Architecture/ADR]
- Inference chain: [Analysis grounded in `sequential-thinking`]
- Analogy: [Known analogous failure in other systems if applicable]

**Impact**:
- [What happens if unfixed]

**Suggestion**:
- [Smallest corrective direction]
```

---

## Quality gate before handoff

### What to do

Self-check against the list: citations, inference, severity, ADR respect, actionability; remove duplicates and hollow language; confirm alignment with parent/child merge rules for challenge (single write path to parent agent—this skill only delivers blocks).

### Why

Ungated design blocks corrupt the contract model—false P0 or missed real closure gaps.

### How to verify

- Every finding has concrete doc references—not vague “architecture doc”.
- Every finding states impact explicitly; Critical/High satisfy enforced `sequential-thinking` on RS/EI.
- No pure guesses without inference chains.
- ADR-recorded trade-offs are not challenged again without new evidence.
- Suggestions point to minimal fixes reviewers can execute.

---

## Subagent orchestration

**Optional**: Where the environment supports parallelization and context split, parent may delegate **each dimension (SD / RS / EI)** or **“doc read-only consolidated summary”** to subagents; subagents return only structured draft findings with anchors and **must not** write `07_CHALLENGE_REPORT.md` themselves.

**Parent agent**: Merge into challenge report shape, dedupe, unify DR numbering, execute Step 4.5 and routing language; **single write path**.

**Handoff checklist (subagent → parent)**:

- Dimensions executed and mandatory file list declared.
- Each draft contains: dimension, suggested severity, anchor, one-sentence finding / impact / suggestion.
- RS and EI drafts declare `sequential-thinking` executed or blocking note.
- No implicit premises conflicting with contracts already loaded by parent; conflicting items isolated under “Needs parent ruling”.
- After merge, subagent does not independently modify the same report path again.

---

<completion_criteria>
- Read `02_ARCHITECTURE_OVERVIEW.md`, `04_SYSTEM_DESIGN/*`, `03_ADR/*` (and PRD from challenge context if available).
- Pre-mortem hypotheses and three-dimensional table scan complete; RS and EI satisfy mandatory `sequential-thinking` rounds.
- Output includes summary table, core findings (finding / impact / suggestion each one sentence), and Critical/High detail blocks—all anchors traceable.
- Quality gate executed; no evidence-free items, no duplicate laundry lists, ADR trade-offs handled correctly.
- Role boundary clear: deliver mergeable design evidence blocks; do not replace `/challenge` final judgment and write duties (unless session explicitly designates you parent agent with write ownership).
</completion_criteria>

