# Design Review Process

## Objective
Determine whether the technical design document is sound enough to proceed to implementation at an acceptable level of risk, through a structured and interactive quality review.

---

## Review Philosophy
- **Quality assurance, not perfection**: The standard is "good enough to build without high failure risk", not "flawless"
- **Critical focus**: Surface only the issues that genuinely threaten success — maximum three
- **Interactive dialogue**: This is a conversation with the design author, not a one-way audit
- **Balanced assessment**: Acknowledge what the design does well alongside what needs attention
- **Decisive output**: Every review ends with a clear GO or NO-GO, not a list of open questions

---

## Scope and Non-Goals

**In scope**: Evaluate design quality against project context, standards, and requirements to produce a GO/NO-GO decision.

**Out of scope**: Deep technology research, finalizing technology choices, performing implementation-level design, or resolving open architecture questions. Flag items that need further design iteration rather than resolving them during the review.

---

## Review Criteria

### 1. Alignment with Existing Architecture (Primary)
- Does the design integrate cleanly with established system boundaries and layers?
- Are the selected patterns consistent with the documented architectural conventions in steering?
- Is dependency direction correct, and does coupling stay within acceptable bounds?
- Does the module organization follow established conventions?

### 2. Design Consistency and Standards
- Do naming conventions, error handling strategies, and logging approaches match the project's established norms?
- Is configuration and dependency management handled consistently with the rest of the system?
- Does data modeling follow the established patterns for this domain?

### 3. Extensibility and Maintainability
- Is the design flexible enough to accommodate likely future requirements without major rework?
- Are concerns separated clearly, with single responsibilities assigned to each component?
- Is the design testable and debuggable in isolation?
- Is the complexity proportionate to what the requirements actually demand?

### 4. Type Safety and Interface Clarity
- Are all public interface contracts explicitly typed with appropriate precision?
- Are unsafe patterns (e.g., `any` in TypeScript, unchecked casts) absent from interface definitions?
- Are API boundaries and data structure contracts sufficiently clear for independent implementation?
- Are all identified error paths covered in the interface contracts?

---

## Review Process

### Step 1: Analyze
Read the design document against all four criteria above. Focus on issues that would create integration problems, maintenance burden, or implementation failures — not stylistic preferences.

### Step 2: Identify Critical Issues (Maximum 3)
For each critical issue found, produce a structured entry:

```
Critical Issue [1–3]: [Short descriptive title]
Concern: [What specifically is wrong or missing]
Impact: [Why this matters — what breaks or degrades if unaddressed]
Suggestion: [A concrete, implementable improvement]
Traceability: [The requirement ID(s) from requirements.md affected by this issue]
Evidence: [The section, heading, or artifact in design.md where the issue is visible]
```

Only escalate issues that materially risk implementation success. Style concerns, minor ambiguities, or optimization opportunities do not qualify as critical issues.

### Step 3: Acknowledge Design Strengths
Identify one to two aspects of the design that demonstrate good judgment — sound architectural choices, clear contracts, well-considered trade-offs. This ensures the feedback is balanced and credible.

### Step 4: Issue GO/NO-GO Decision

**GO** (proceed to task generation) when:
- No critical architectural conflicts exist
- All requirements have a credible path to implementation
- The implementation path is clear and the risks are understood and manageable

**NO-GO** (revise before proceeding) when:
- A fundamental architectural conflict exists that would cause failure or major rework
- One or more requirements have no viable implementation path in the current design
- Complexity or coupling is disproportionate to requirements and creates high failure risk

---

## Traceability and Evidence Standards

Every critical issue must include:
- **Traceability**: The requirement ID(s) from `requirements.md` that are affected (numeric IDs, e.g., `1.1`, `2.3`)
- **Evidence**: The specific section, heading, diagram, or component in `design.md` where the issue is located
- When applicable: a reference to a steering document principle that the design violates

---

## Output Format

### Design Review Summary
Two to three sentences summarizing overall quality and readiness.

### Critical Issues (Maximum 3)
Each issue: Concern, Impact, Suggestion, Traceability (requirement IDs), Evidence (design.md location).

### Design Strengths
One to two positive aspects that reflect sound design thinking.

### Final Assessment
Decision (GO / NO-GO), Rationale (one to two sentences), Next Steps (specific and actionable).

### Interactive Discussion
Invite the author to share their perspective on each critical issue, propose alternatives, or clarify intent before the final decision is confirmed.

---

## Length and Focus Guidelines

- **Summary**: 2–3 sentences
- **Each critical issue**: 5–7 lines covering all required fields
- **Total review**: Aim for approximately 400 words — concise enough to be read and acted on immediately

---

## Review Quality Checklist

Before delivering the review, confirm:
- [ ] No more than 3 critical issues are listed
- [ ] Each issue includes Impact and Suggestion (not just identification)
- [ ] Each issue references at least one requirement ID for traceability
- [ ] Each issue cites a specific location in `design.md` as evidence
- [ ] At least one design strength is acknowledged
- [ ] The final decision is explicitly stated as GO or NO-GO with rationale
- [ ] Next steps are concrete and actionable for either outcome
