Design Review Gate

The Gate Before Phase 3

Before moving to implementation, run a design review. This is the gate that catches over-engineering, scope creep, and missing decisions. Every "no" in this checklist is a design gap that will surface as a bug, a rework session, or a surprised stakeholder in Phase 3.

Design review checklist

Dimension	Question	Red Flag
Scope	Is the boundary between "in scope" and "out of scope" explicit?	"We'll figure it out during implementation"
Over-reach	Did Claude add features not in the spec? Were they removed?	Extra abstractions, unused interfaces, speculative features
Simplicity	Is this the simplest design that meets the requirements?	Abstract factory for one implementation
Consistency	Does the design follow existing patterns in the codebase?	"Claude suggested a better approach"
Persistence	Are all decisions in files (architecture, CLAUDE.md)?	"We discussed it in the last session"
Error handling	Are error formats and failure modes defined?	"We'll use standard error handling"
Testability	Can the design be verified with automated tests?	"We'll test it manually"
Security surface	Are input boundaries and access controls defined?	"We'll add security later"

Watch for over-reach

Over-reach check from field experience: AI has a natural tendency to autonomously extend the solution space beyond what is necessary — generating grandiose architectures, unnecessary abstractions, or speculative features. Review for scope creep: did Claude add features not in the spec? Remove them. Guard against uncontrolled expansion.

The Phase 2 checkpoint

Verify you have the complete design artifact chain:

Artifact	Location	Purpose
Architecture plan	`docs/architecture/task-comments.md`	Codebase analysis, trade-offs, chosen approach, error format, response shapes
CLAUDE.md	`CLAUDE.md`	Pointers to active work — read every session
ADR (optional)	`docs/adr/ADR-001-task-comments.md`	Decision reasoning for future maintainers

These artifacts are the input for Phase 3. The implementation prompt in Phase 3 will say: "Implement the feature as specified in docs/specs/task-comments.md, following the architecture in docs/architecture/task-comments.md." Claude reads CLAUDE.md, discovers the active work, and implements precisely what the spec and architecture specify.

Turn the Design Review into a Reusable Skill First

Rather than run the design review by hand and then repackage it as a skill, package the skill first — then run the review with it. You just did the same thing for validate-spec: the skill file is the contract, plain text on disk, no LLM required to write it.

The design-review skill is the architecture-stage counterpart to validate-spec from earlier in this phase. Both check quality at a gate. Both use a structured checklist. In Phase 4 (Ralph Loop) both are invoked by the autonomous pipeline — validate-spec before architecture, design-review before implementation — so every deferred unit passes through the same gates you are building by hand here.

What a Design-Review Skill Looks Like

---
name: design-review
description: Review an architecture plan against its spec for scope, simplicity, and consistency. Use after writing an architecture plan, before handing off to Phase 3 implementation.
disable-model-invocation: true
argument-hint: [path to architecture plan]
---

Review the architecture plan at $ARGUMENTS.

Check against these dimensions:
1. Scope — is in/out of scope boundary explicit relative to the spec?
2. Over-reach — did Claude add features not in the spec? List them.
3. Simplicity — is this the simplest design that meets the requirements?
   Flag: abstract factories for one implementation, unnecessary interfaces, speculative features.
4. Consistency — does the design follow existing codebase patterns?
5. Persistence — are all decisions in files, not just in conversation?

For each dimension:
- PASS if no issues
- FAIL with specific description if issues found

Fix any FAIL items in the architecture plan directly. Report what changed.

The argument-hint tells autocomplete what to pass

The argument-hint: [path to architecture plan] tells autocomplete what to pass. Type /design-review docs/architecture/task-comments.md and Claude reviews exactly that plan. The same skill works for every feature's architecture doc — no customization needed.

Hands-On: Create the Skill and Run the Review

TRY IT: Package the checklist as a skill, then run the review

You are in the taskflow folder with all Phase 2 artifacts complete. Create the skill directly from the shell, start a fresh session, and run the review with it.

Step 1 — Exit Claude: Drop to the shell so you can write the skill file.

Run in terminal:

1
/exit

Step 2 — Write the skill file: Create .claude/skills/design-review/SKILL.md with the frontmatter and body below. The $ARGUMENTS placeholder is replaced at runtime with whatever you pass after /design-review.

Run in terminal:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
mkdir -p .claude/skills/design-review && cat > .claude/skills/design-review/SKILL.md << 'EOF'
---
name: design-review
description: Review an architecture plan against its spec for scope, simplicity, and consistency. Use before Phase 3 handoff.
disable-model-invocation: true
argument-hint: [path to architecture plan]
---

Review the architecture plan at $ARGUMENTS against the spec in docs/specs/ and CLAUDE.md.

Check against these dimensions:
1. Scope — is in/out of scope boundary explicit relative to the spec?
2. Over-reach — did Claude add features not in the spec? List them.
3. Simplicity — is this the simplest design that meets the requirements?
   Flag: abstract factories for one implementation, unnecessary interfaces, speculative features.
4. Consistency — does the design follow existing codebase patterns?
5. Persistence — are all decisions in files, not just in conversation?

For each dimension:
- PASS if no issues
- FAIL with specific description if issues found

Fix any FAIL items in the architecture plan directly. Report what changed.
EOF

Observe: The skill file now exists on disk. No Claude session involved. That is the point — skills are plain text contracts.

Step 3 — Start a new session: Skills are discovered at session start, so the next claude invocation will pick it up.

Run in terminal:

1
claude

Step 4 — Run the review: Invoke the skill against the architecture plan.

Tell Claude:

/design-review docs/architecture/task-comments.md

Observe: Claude runs the five-dimension check and typically finds 1–2 issues: an over-engineered component, a missing error case, or an inconsistency with existing code patterns. If it finds issues, tell Claude to fix them — it will update the architecture file in place. These are the issues that would have become bugs in Phase 3.

Phase 2 complete

Phase 2 is complete. You've gone from a validated spec to a reviewed design: architecture plan (with error format and response shapes) and CLAUDE.md pointing to the active work. Every decision is in a file. Phase 3 starts from this foundation — Claude reads CLAUDE.md, discovers the spec and architecture, and implements precisely what they specify.

Two skills down, one to go

You now have two skills — validate-spec (earlier in this phase) and design-review (just now). In Phase 3 you will add self-review. All three are reused by Phase 4's Ralph Loop as automated quality gates: validate-spec runs on every new spec before architecture, design-review runs on every architecture plan before implementation, self-review runs on every implementation before it's marked done. The skills you are building here are the production gates the autonomous pipeline will enforce.