Design Review

Design Review

Review a design or specification document against real-world patterns in the codebase.

Process

Step 1: Understand the Design

Read the design document at $ARGUMENTS in its entirety. Do not assume prior knowledge. Pay close attention to:

• Intent and goals (what problem is being solved?)
• Core concepts and models
• Categories, classifications, or taxonomies
• Confidence levels or open questions noted by the author

Step 2: Understand the Problem Domain

Trace the existing codebase to understand how the system currently works. This is NOT to compare implementation to spec—the implementation may change. This is to understand:

• Edge cases the design must handle
• Current patterns and how they flow
• Integration points with external systems

Search for relevant code using Glob and Grep. Look for:

• Core logic related to the design's domain
• Error handling and validation
• Test fixtures and edge case tests

Step 3: Find Real Problematic Patterns

Search the codebase for concrete examples that would stress the design:

• Test fixtures with intentionally difficult cases
• Edge case tests
• Real failures from test runs (log files, output captures)
• Integration tests with external systems

Step 4: Evaluate Design Against Patterns

For each problematic pattern found:

1. How would the design handle this case?
2. What category/classification applies?
3. What would the output look like?
4. Is the design unclear, insufficient, or missing coverage?

Output Format

## Design Review: [Document Name]

### Summary

[2-3 sentence assessment of design soundness]

---

## Concrete Scenarios Found

### 1. [Pattern Name] (source)

**Scenario**: [What the pattern is] **Actual data**: [Real example if available]
**How design handles**: [Section, category, or classification that applies]
**Problem**: [Gap, ambiguity, or incorrect handling] **Recommendation**:
[Specific fix]

[Repeat for each significant pattern]

---

## Design Strengths

[What the design gets right, validated by real patterns]

---

## Recommended Changes

### [Category]

| Item | Description | Rationale |
| ---- | ----------- | --------- |
| ...  | ...         | ...       |

What NOT to Output

• Implementation gaps ("X isn't built yet")
• Implementation tasks ("implement Y")
• Comparison of spec to current code behavior
• Time estimates

Focus on design completeness and correctness, not implementation status.

Source: dgellow/steady — distributed by TomeVault.