# Design Review

> Review design artifacts (problem statements, decision matrices, scope documents) for rigor, completeness, and adherence to Design in Practice principles.

- Skill: `majiayu000/design-review-6` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/design-review-6`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/design-review-6/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/design-review-6

---


# Design Artifact Review

Review design artifacts for rigor, completeness, and adherence to Design in Practice principles.

## Setup

**If artifact path provided:** Read the artifact completely
**If no path:** Ask which artifact to review, or list available design documents

## Review Framework

Perform targeted review based on artifact type. Each review checks for common failure modes that lead to poor solutions.

---

## ARTIFACT TYPE: Problem Statement

### Check 1: Solution Contamination

**Question:** Does the problem statement contain or imply solutions?

**Red flags:**
- "We need to..." (solution language)
- Technology names (Redis, Kafka, etc.) unless they ARE the problem
- "Add", "implement", "create", "build" verbs
- Comparison to how other systems work

**Test:** Could multiple fundamentally different solutions address this statement?
- YES → Good problem statement (solution-agnostic)
- NO → Solution is embedded, rewrite needed

**Output:**
```
Solution Contamination: [CLEAN | CONTAMINATED]

Evidence:
- [Quote from statement showing contamination, or "None found"]

Recommendation:
- [How to remove solution language]
```

### Check 2: Root Cause vs. Symptom

**Question:** Does this describe the mechanism, or just the observable effect?

**Symptom language:**
- "Users experience..."
- "The system is slow/broken/failing..."
- "Errors occur when..."

**Mechanism language:**
- "Because X happens, Y results in Z"
- "The [component] does [action] which causes [effect]"
- Clear causal chain

**Test:** Ask "Why?" - if there's a deeper answer, this is a symptom.

**Output:**
```
Root Cause Analysis: [MECHANISM | SYMPTOM | UNCLEAR]

Depth check:
- Statement says: [quote]
- Ask "Why?": [deeper cause if exists]
- Assessment: [Is this the root or just a layer?]

Recommendation:
- [How to dig deeper, or "Root cause identified"]
```

### Check 3: Specificity

**Question:** Is the problem precise enough to guide solution selection?

**Vague indicators:**
- "Performance issues" (which metric? what threshold?)
- "Users are confused" (which users? confused about what?)
- "The code is messy" (what aspect? what's the impact?)

**Specific indicators:**
- Quantified thresholds ("response time > 2s")
- Named components ("SessionManager.close()")
- Reproducible conditions ("when concurrent users > 50")

**Output:**
```
Specificity: [PRECISE | VAGUE | MIXED]

Vague elements:
- [Element 1]: [How to make specific]
- [Element 2]: [How to make specific]

Missing specifics:
- [What metric/threshold/condition is unclear]
```

### Check 4: Evidence Quality

**Question:** Is the diagnosis based on verified facts or assumptions?

**Look for:**
- Evidence cited for each claim
- Ruled-out alternatives documented
- Hypothesis testing described
- Data sources referenced

**Output:**
```
Evidence Quality: [VERIFIED | ASSUMED | MIXED]

Claims without evidence:
- [Claim 1]: [What evidence is needed]
- [Claim 2]: [What evidence is needed]

Ruled-out alternatives:
- [Listed? How many? Are they reasonable alternatives?]
```

### Check 5: The Obvious Solution Test

**Question:** Does the solution feel obvious after reading this statement?

If the reader finishes the problem statement and doesn't immediately think "oh, we should do X", the diagnosis is incomplete.

**Output:**
```
Obvious Solution Test: [PASS | FAIL | PARTIAL]

After reading, the obvious action is: [What seems like the right solution]

If FAIL:
- What's unclear: [What question remains]
- What's missing: [What would make it obvious]
```

### Problem Statement Verdict

```
## Problem Statement Review Summary

| Check | Result | Action Needed |
|-------|--------|---------------|
| Solution Contamination | [CLEAN/CONTAMINATED] | [Action or "None"] |
| Root Cause | [MECHANISM/SYMPTOM] | [Action or "None"] |
| Specificity | [PRECISE/VAGUE] | [Action or "None"] |
| Evidence | [VERIFIED/ASSUMED] | [Action or "None"] |
| Obvious Solution | [PASS/FAIL] | [Action or "None"] |

**Verdict:** [READY_FOR_DIRECTION | NEEDS_REVISION | BACK_TO_DESCRIBE]

**Top Issue:** [Most critical thing to fix]

**Recommended Action:** [Specific next step]
```

---

## ARTIFACT TYPE: Decision Matrix

### Check 1: Status Quo Baseline

**Question:** Is "do nothing" the first column?

The Status Quo:
- Provides baseline for comparison
- Forces articulation of current state costs
- Prevents "solution in search of problem"

**Output:**
```
Status Quo Baseline: [PRESENT | MISSING]

If missing:
- Impact: Cannot compare alternatives to current state
- Fix: Add Status Quo column with honest assessment
```

### Check 2: Fact vs. Judgment Separation

**Question:** Is cell text factual and neutral, with judgment shown separately?

**Contaminated cells:**
- "Good performance" (judgment as text)
- "Easy to implement" (subjective)
- "Better than X" (comparative judgment)

**Clean cells:**
- "< 10ms p99 latency" (measurable fact)
- "Requires changes to 3 files" (countable)
- "Uses existing auth pattern" (verifiable)

**Output:**
```
Fact/Judgment Separation: [CLEAN | CONTAMINATED]

Contaminated cells:
| Row | Column | Current Text | Factual Rewrite |
|-----|--------|--------------|-----------------|
| [Row] | [Col] | "[Text]" | "[Suggestion]" |

Assessment indicators:
- Are judgments (good/bad) shown via color/symbol, not text? [YES/NO]
```

### Check 3: Criteria Completeness

**Question:** Are all relevant trade-off dimensions represented?

**Common missing criteria:**
- Maintenance burden (long-term cost)
- Rollback difficulty (reversibility)
- Team expertise (can we actually do this?)
- Integration complexity (how it affects other systems)
- Failure modes (what happens when it breaks?)

**Output:**
```
Criteria Completeness: [COMPLETE | GAPS]

Present criteria: [List]

Potentially missing:
- [Criterion]: [Why it matters for this decision]
- [Criterion]: [Why it matters for this decision]

Recommendation:
- [Which criteria to add]
```

### Check 4: Approach Diversity

**Question:** Are the approaches fundamentally different, or variations of the same idea?

**Insufficient diversity:**
- "Option A: Use Redis" / "Option B: Use Memcached" (same category)
- All options involve adding something (no "remove feature" option)
- All options are technical (no process/product options)

**Good diversity:**
- Different architectural approaches
- Build vs. Buy vs. Remove
- Technical vs. Process vs. Product solutions

**Output:**
```
Approach Diversity: [DIVERSE | SIMILAR]

Approaches listed:
- [Approach 1]: [Category]
- [Approach 2]: [Category]
- [Approach 3]: [Category]

Missing perspectives:
- [What category of solution wasn't considered]
```

### Check 5: Cell Verification

**Question:** Are the facts in the matrix verifiable and accurate?

Spot-check 2-3 claims:
- Can this be verified in the codebase?
- Is this number accurate?
- Is this comparison fair?

**Output:**
```
Cell Verification: [VERIFIED | UNVERIFIED | ERRORS]

Spot checks:
- [Cell Row/Col]: [Claim] → [Verification result]
- [Cell Row/Col]: [Claim] → [Verification result]

Errors found:
- [Cell]: [What's wrong and what's correct]
```

### Decision Matrix Verdict

```
## Decision Matrix Review Summary

| Check | Result | Action Needed |
|-------|--------|---------------|
| Status Quo Baseline | [PRESENT/MISSING] | [Action or "None"] |
| Fact/Judgment Separation | [CLEAN/CONTAMINATED] | [Action or "None"] |
| Criteria Completeness | [COMPLETE/GAPS] | [Action or "None"] |
| Approach Diversity | [DIVERSE/SIMILAR] | [Action or "None"] |
| Cell Verification | [VERIFIED/ERRORS] | [Action or "None"] |

**Verdict:** [READY_FOR_DECISION | NEEDS_REVISION | NEEDS_MORE_OPTIONS]

**Selected approach justified?** [YES/NO - Is the rationale sound?]

**Top Issue:** [Most critical thing to fix]

**Recommended Action:** [Specific next step]
```

---

## ARTIFACT TYPE: Scope Document (Delimit Phase)

### Check 1: Explicit Non-Goals

**Question:** Are out-of-scope items explicitly listed?

Scope creep happens when boundaries are implicit. Explicit non-goals:
- Prevent "while we're in there" additions
- Set expectations with stakeholders
- Provide reference when scope questions arise

**Output:**
```
Non-Goals: [EXPLICIT | IMPLICIT | MISSING]

Listed non-goals: [count]

Likely scope creep vectors not addressed:
- [Related item that might get added]
- [Adjacent problem that might expand scope]
```

### Check 2: Constraint Realism

**Question:** Are the constraints achievable and honest?

Look for:
- Conflicting constraints ("fast AND cheap AND complete")
- Unstated constraints (timeline, budget, expertise)
- Over-optimistic assumptions

**Output:**
```
Constraints: [REALISTIC | OPTIMISTIC | CONFLICTING]

Constraint conflicts:
- [Constraint A] vs [Constraint B]: [Why they conflict]

Missing constraints:
- [What's unstated but will affect the work]
```

---

## COMBINED REVIEW (Full Design Package)

When reviewing Problem Statement + Decision Matrix + Plan together:

### Alignment Check

1. **Problem → Direction alignment:**
   - Does the selected approach actually address the diagnosed problem?
   - Or does it solve a different/adjacent problem?

2. **Scope → Plan alignment:**
   - Does the plan stay within stated scope?
   - Are non-goals respected in the implementation?

3. **Decision rationale → Plan execution:**
   - Does the plan leverage the reasons the approach was chosen?
   - Are accepted trade-offs reflected in implementation?

**Output:**
```
## Alignment Review

Problem → Direction: [ALIGNED | DRIFT]
- [Evidence of alignment or drift]

Scope → Plan: [ALIGNED | CREEP]
- [Evidence of scope adherence or creep]

Decision → Plan: [ALIGNED | INCONSISTENT]
- [Does plan execute on decision rationale?]
```

---

## Final Report Template

```
## Design Artifact Review Report

**Artifact(s) Reviewed:** [List]
**Date:** [YYYY-MM-DD]

### Summary

| Artifact | Verdict | Key Issues |
|----------|---------|------------|
| Problem Statement | [READY/REVISION/BACK] | [Top issue] |
| Decision Matrix | [READY/REVISION/MORE] | [Top issue] |
| Scope Document | [READY/REVISION] | [Top issue] |
| Alignment | [ALIGNED/DRIFT] | [Top issue] |

### Critical Findings

1. **[ARTIFACT-CHECK]** [Severity]
   - Issue: [What's wrong]
   - Impact: [Why it matters]
   - Fix: [Specific action]

2. **[ARTIFACT-CHECK]** [Severity]
   - Issue: [What's wrong]
   - Impact: [Why it matters]
   - Fix: [Specific action]

### Recommended Actions

1. [Most important action]
2. [Second action]
3. [Third action]

### Overall Verdict

[PROCEED_TO_IMPLEMENTATION | REVISE_ARTIFACTS | RETURN_TO_EARLIER_PHASE]

**Rationale:** [1-2 sentences]
```