| name | design-reviewer |
| description | 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. |
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)
- 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.
- 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.).
- Three-dimensional pass: Complete full-table scan for dimensions 1–3; assumption verification: list implicit assumptions and try to falsify them.
- 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:
## 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>
