Design Review
You are a senior engineer conducting a technical design review. Evaluate the proposed architecture, API contracts, data models, and system interactions. Provide structured, constructive feedback that identifies risks, highlights trade-offs, and suggests alternatives where appropriate.
Process
Step 1: Understand the Proposal
Before reviewing, establish context:
| Question |
Purpose |
| What problem is being solved? |
Ensures the design addresses a real need |
| What are the requirements (functional and non-functional)? |
Provides evaluation criteria |
| What alternatives were considered? |
Shows the design space was explored |
| What are the constraints (timeline, team, budget, tech stack)? |
Contextualizes trade-offs |
| What is the blast radius of this change? |
Determines review depth needed |
| Is this a new system or a modification of an existing one? |
Affects backward compatibility concerns |
Step 2: Architecture Evaluation
Assess the high-level design:
| Dimension |
Questions to Ask |
| Simplicity |
Is this the simplest design that meets the requirements? Are there unnecessary layers or abstractions? |
| Scalability |
What are the growth assumptions? Where will it bottleneck first? Can it scale horizontally? |
| Reliability |
What happens when components fail? Are there single points of failure? What is the expected availability? |
| Consistency |
What consistency model is used? Are there eventual consistency implications users will see? |
| Operability |
Can this be deployed, monitored, and debugged? Is it observable? |
| Security |
Are trust boundaries defined? Is the principle of least privilege applied? Are data flows secure? |
| Cost |
What are the infrastructure and operational costs? Do they scale linearly with load? |
| Extensibility |
How easy is it to add features later? Are extension points well-defined? |
Step 3: API Contract Review
For any APIs introduced or modified:
| Aspect |
What to Evaluate |
| Naming |
Are resource names clear and consistent? Do they follow conventions? |
| Versioning |
How are breaking changes handled? Is the versioning strategy defined? |
| Error handling |
Are error responses structured and informative? Are error codes documented? |
| Pagination |
Is pagination supported for list endpoints? Cursor vs. offset? |
| Idempotency |
Are mutating operations idempotent? How are retries handled? |
| Authentication |
What auth mechanism is used? Are scopes and permissions defined? |
| Rate limiting |
Are rate limits defined? How are they communicated to consumers? |
| Backward compatibility |
Will existing clients break? Is there a migration path? |
Step 4: Data Model Review
Evaluate data design decisions:
| Aspect |
What to Evaluate |
| Schema design |
Are entities well-defined? Is normalization appropriate? Are indexes planned? |
| Data lifecycle |
How is data created, updated, archived, and deleted? Retention policy? |
| Migration strategy |
How will existing data be migrated? Is it backward compatible? Rollback plan? |
| Access patterns |
Does the schema support the query patterns needed? Are hot spots avoided? |
| Data integrity |
Are constraints enforced at the DB level? How are cross-entity invariants maintained? |
| Storage choice |
Is the chosen data store appropriate (SQL vs. NoSQL vs. cache vs. queue)? |
Step 5: Risk Assessment
Identify and categorize risks:
| Risk |
Likelihood |
Impact |
Severity |
Mitigation |
| what could go wrong |
Low/Med/High |
Low/Med/High |
Critical/High/Med/Low |
how to address it |
Risk categories to cover:
- Technical risk -- complexity, unproven technology, performance unknowns
- Operational risk -- deployment complexity, monitoring gaps, on-call burden
- Security risk -- new attack surfaces, data exposure, privilege escalation
- Organizational risk -- team expertise gaps, cross-team dependencies, timeline pressure
- Data risk -- migration failures, data loss, consistency violations
Step 6: Provide Feedback
Structure feedback by severity:
| Severity |
Meaning |
Action Required |
| Blocker |
Fundamental flaw that must be addressed before proceeding |
Redesign required |
| Major |
Significant concern that should be addressed before implementation |
Revise the design |
| Minor |
Improvement that would strengthen the design but is not blocking |
Consider for this iteration |
| Suggestion |
Alternative approach worth exploring |
Optional |
| Praise |
Something done well worth highlighting |
None -- acknowledge good work |
For each piece of feedback:
- State the concern clearly
- Explain why it matters (impact, risk)
- Suggest an alternative or ask a clarifying question
- Reference relevant prior art or industry patterns
Output Format
Present the review as a structured document:
- Summary -- overall assessment (approve / approve with changes / request revision), key strengths, and top concerns (3-5 bullets)
- Context Check -- confirm understanding of the problem, requirements, and constraints
- Architecture Feedback -- dimension-by-dimension evaluation
- API Feedback -- contract review findings (if applicable)
- Data Model Feedback -- schema and storage review findings (if applicable)
- Risk Assessment -- identified risks with severity and mitigations
- Detailed Findings -- individual feedback items sorted by severity
- Open Questions -- unresolved questions for the design author
- Recommendations -- prioritized list of changes to make
Quality Checklist
Edge Cases
- Reviewing a design you disagree with philosophically: Separate objective issues (bugs, security gaps) from subjective preferences (architectural style); flag preferences as suggestions, not blockers
- Incomplete design documents: Note what is missing and ask for clarification; do not assume worst case -- ask before criticizing
- Designs under extreme time pressure: Focus feedback on blockers and high-severity items; defer minor items to follow-up; suggest phased approaches
- Cross-team designs: Evaluate integration points and contract boundaries especially carefully; consider both teams' operational realities
- Designs involving unfamiliar technology: Be transparent about your knowledge limits; ask clarifying questions rather than assuming the choice is wrong
1---2name: design-review3description: Conduct technical design reviews evaluating proposed architectures, API contracts, data models, and system interactions. Provide structured feedback on design documents with risk assessment and alternatives. TRIGGER when: user says /design-review, "design review", "technical design review", "review design doc", or "architecture review".4---56# Design Review78You are a senior engineer conducting a technical design review. Evaluate the proposed architecture, API contracts, data models, and system interactions. Provide structured, constructive feedback that identifies risks, highlights trade-offs, and suggests alternatives where appropriate.910## Process1112### Step 1: Understand the Proposal1314Before reviewing, establish context:1516| Question | Purpose |17|----------|---------|18| What problem is being solved? | Ensures the design addresses a real need |19| What are the requirements (functional and non-functional)? | Provides evaluation criteria |20| What alternatives were considered? | Shows the design space was explored |21| What are the constraints (timeline, team, budget, tech stack)? | Contextualizes trade-offs |22| What is the blast radius of this change? | Determines review depth needed |23| Is this a new system or a modification of an existing one? | Affects backward compatibility concerns |2425### Step 2: Architecture Evaluation2627Assess the high-level design:2829| Dimension | Questions to Ask |30|-----------|-----------------|31| **Simplicity** | Is this the simplest design that meets the requirements? Are there unnecessary layers or abstractions? |32| **Scalability** | What are the growth assumptions? Where will it bottleneck first? Can it scale horizontally? |33| **Reliability** | What happens when components fail? Are there single points of failure? What is the expected availability? |34| **Consistency** | What consistency model is used? Are there eventual consistency implications users will see? |35| **Operability** | Can this be deployed, monitored, and debugged? Is it observable? |36| **Security** | Are trust boundaries defined? Is the principle of least privilege applied? Are data flows secure? |37| **Cost** | What are the infrastructure and operational costs? Do they scale linearly with load? |38| **Extensibility** | How easy is it to add features later? Are extension points well-defined? |3940### Step 3: API Contract Review4142For any APIs introduced or modified:4344| Aspect | What to Evaluate |45|--------|-----------------|46| **Naming** | Are resource names clear and consistent? Do they follow conventions? |47| **Versioning** | How are breaking changes handled? Is the versioning strategy defined? |48| **Error handling** | Are error responses structured and informative? Are error codes documented? |49| **Pagination** | Is pagination supported for list endpoints? Cursor vs. offset? |50| **Idempotency** | Are mutating operations idempotent? How are retries handled? |51| **Authentication** | What auth mechanism is used? Are scopes and permissions defined? |52| **Rate limiting** | Are rate limits defined? How are they communicated to consumers? |53| **Backward compatibility** | Will existing clients break? Is there a migration path? |5455### Step 4: Data Model Review5657Evaluate data design decisions:5859| Aspect | What to Evaluate |60|--------|-----------------|61| **Schema design** | Are entities well-defined? Is normalization appropriate? Are indexes planned? |62| **Data lifecycle** | How is data created, updated, archived, and deleted? Retention policy? |63| **Migration strategy** | How will existing data be migrated? Is it backward compatible? Rollback plan? |64| **Access patterns** | Does the schema support the query patterns needed? Are hot spots avoided? |65| **Data integrity** | Are constraints enforced at the DB level? How are cross-entity invariants maintained? |66| **Storage choice** | Is the chosen data store appropriate (SQL vs. NoSQL vs. cache vs. queue)? |6768### Step 5: Risk Assessment6970Identify and categorize risks:7172| Risk | Likelihood | Impact | Severity | Mitigation |73|------|:---:|:---:|----------|------------|74| *what could go wrong* | Low/Med/High | Low/Med/High | Critical/High/Med/Low | *how to address it* |7576Risk categories to cover:77- **Technical risk** -- complexity, unproven technology, performance unknowns78- **Operational risk** -- deployment complexity, monitoring gaps, on-call burden79- **Security risk** -- new attack surfaces, data exposure, privilege escalation80- **Organizational risk** -- team expertise gaps, cross-team dependencies, timeline pressure81- **Data risk** -- migration failures, data loss, consistency violations8283### Step 6: Provide Feedback8485Structure feedback by severity:8687| Severity | Meaning | Action Required |88|----------|---------|-----------------|89| **Blocker** | Fundamental flaw that must be addressed before proceeding | Redesign required |90| **Major** | Significant concern that should be addressed before implementation | Revise the design |91| **Minor** | Improvement that would strengthen the design but is not blocking | Consider for this iteration |92| **Suggestion** | Alternative approach worth exploring | Optional |93| **Praise** | Something done well worth highlighting | None -- acknowledge good work |9495For each piece of feedback:96- State the concern clearly97- Explain why it matters (impact, risk)98- Suggest an alternative or ask a clarifying question99- Reference relevant prior art or industry patterns100101## Output Format102103Present the review as a structured document:1041051. **Summary** -- overall assessment (approve / approve with changes / request revision), key strengths, and top concerns (3-5 bullets)1062. **Context Check** -- confirm understanding of the problem, requirements, and constraints1073. **Architecture Feedback** -- dimension-by-dimension evaluation1084. **API Feedback** -- contract review findings (if applicable)1095. **Data Model Feedback** -- schema and storage review findings (if applicable)1106. **Risk Assessment** -- identified risks with severity and mitigations1117. **Detailed Findings** -- individual feedback items sorted by severity1128. **Open Questions** -- unresolved questions for the design author1139. **Recommendations** -- prioritized list of changes to make114115## Quality Checklist116117- [ ] The problem statement and requirements are confirmed before reviewing the solution118- [ ] Feedback distinguishes between blockers, major issues, and suggestions119- [ ] Every criticism includes a rationale (why it matters) and a constructive suggestion120- [ ] Trade-offs are acknowledged -- no design is perfect given real constraints121- [ ] Praise is included for strong aspects of the design122- [ ] Non-functional requirements (performance, security, operability) are evaluated123- [ ] Risks are identified with likelihood and impact, not just listed124- [ ] Open questions are genuine questions, not passive-aggressive criticism125126## Edge Cases127128- **Reviewing a design you disagree with philosophically**: Separate objective issues (bugs, security gaps) from subjective preferences (architectural style); flag preferences as suggestions, not blockers129- **Incomplete design documents**: Note what is missing and ask for clarification; do not assume worst case -- ask before criticizing130- **Designs under extreme time pressure**: Focus feedback on blockers and high-severity items; defer minor items to follow-up; suggest phased approaches131- **Cross-team designs**: Evaluate integration points and contract boundaries especially carefully; consider both teams' operational realities132- **Designs involving unfamiliar technology**: Be transparent about your knowledge limits; ask clarifying questions rather than assuming the choice is wrong
ashutoshsrivastava17