/design-review

Conduct a structured design review of a module, feature, or system component.

Steps

1. Identify the scope of review from the argument (module path, feature name, or PR number).
2. Map the component boundaries:
   • Entry points (APIs, event handlers, CLI commands).
   • Internal modules and their responsibilities.
   • External dependencies and integration points.
   • Data flow from input to output.
3. Evaluate against design principles:
   • Single Responsibility: Does each module have one clear purpose?
   • Dependency Direction: Do dependencies flow inward (clean architecture)?
   • Interface Segregation: Are interfaces minimal and focused?
   • Error Handling: Are failures handled consistently and explicitly?
   • Testability: Can components be tested in isolation?
4. Check for common anti-patterns:
   • God objects or modules with too many responsibilities.
   • Circular dependencies between modules.
   • Leaky abstractions exposing internal implementation.
   • Configuration scattered across multiple locations.
5. Assess scalability and operational concerns:
   • Can this handle 10x current load?
   • What are the failure modes and recovery paths?
   • Is observability built in (logging, metrics, tracing)?
6. Produce a structured review with actionable recommendations.

Format

## Design Review: <Component Name>

### Architecture Score: <1-5>/5

### Strengths
- What is well designed

### Concerns
- CRITICAL: Issues that need immediate attention
- WARNING: Issues to address before next milestone

### Recommendations
1. Specific actionable improvement
2. Specific actionable improvement

### Diagram
<Mermaid diagram of current architecture>

Rules

• Be constructive; pair every criticism with a concrete suggestion.
• Focus on structural issues, not cosmetic ones.
• Consider the team's current constraints and pragmatic tradeoffs.
• Reference specific files and line numbers where applicable.