---
name: design-pattern-review
description: Use when reviewing a project's architecture for design pattern applicability -- either validating a design document before implementation, or analyzing an existing codebase for pattern improvement opportunities.
---

# Design Pattern Review

Reviews a project's architecture against known design patterns and outputs a structured report with findings and recommendations.

## When to Use

- You have a design document or architecture spec and want to validate it uses appropriate patterns before coding
- You have an existing codebase and want to identify where patterns could improve structure, maintainability, or extensibility
- You want a systematic first-pass audit of pattern usage before a major refactor

## Flags

- `--design` — force design document review mode
- `--code` — force code review mode
- `--scope <path>` — limit review to a specific directory (e.g., `--scope src/auth/`)

## Process

### Step 1: Auto-Detect Mode

Unless overridden by a flag, detect mode automatically:

1. Scan for design/architecture documents: `docs/**/*.md`, `specs/**/*.md`, `ARCHITECTURE.md`, `DESIGN.md`, files with "architecture" or "design" in the name
2. If design docs found → **Design Doc Review Mode**
3. If no design docs found → **Code Review Mode**

If both design docs and code exist and the user wants both reviewed, run the skill twice: once with `--design`, once with `--code`.

### Step 2: Context Discovery

Before reviewing, gather context:

1. Detect project language(s) from config files:
   - Go: `go.mod`
   - Node/JS/TS: `package.json`
   - Python: `pyproject.toml`, `setup.py`, `requirements.txt`
   - Rust: `Cargo.toml`
   - Java: `pom.xml`, `build.gradle`
2. Note the directory scope (full project or `--scope` path)
3. Load relevant pattern knowledge from `patterns/` based on the project type

### Step 3A: Design Doc Review Mode

1. Read the identified design documents
2. Map described components and interactions to known patterns:
   - Look for explicit pattern mentions and assess if they are correctly applied
   - Look for described behaviors that match pattern signatures (e.g., "plugins that can be swapped" → Strategy; "notifications to multiple subscribers" → Observer)
3. For each unmapped area of the design, consider which patterns could strengthen it
4. Note any anti-patterns or misapplied patterns

**Load relevant pattern files:**
- Check `patterns/creational.md` for object creation concerns
- Check `patterns/structural.md` for component composition and relationships
- Check `patterns/behavioral.md` for interactions and responsibilities
- Check `patterns/modern.md` for data access, resilience, and messaging concerns
- Check `patterns/architectural.md` for overall structure and layering concerns

### Step 3B: Code Review Mode

1. Use Explore agents to scan codebase structure (key directories, entry points, models, handlers)
   - For large codebases without `--scope`: sample entry points, models, handlers, services — do not attempt a full scan
2. Identify code smells that signal pattern opportunities:
   - Large conditional/switch blocks → Strategy, State, or Command
   - Duplicated object creation logic → Factory or Builder
   - Tight coupling between modules → Observer, Mediator, or Dependency Injection
   - God classes or oversized files → Facade, decomposition with patterns
   - Complex multi-step object construction → Builder
   - Cross-cutting concerns (logging, auth, caching) tangled in business logic → Decorator, Proxy
   - Direct database queries scattered across the codebase → Repository
3. Check for patterns already in use and assess correctness
4. Adapt recommendations to the detected language (see language considerations in each pattern file)

**Load relevant pattern files:**
- Check `patterns/creational.md` for object creation concerns
- Check `patterns/structural.md` for composition and coupling concerns
- Check `patterns/behavioral.md` for interaction and responsibility concerns
- Check `patterns/modern.md` for data access, resilience, messaging
- Check `patterns/architectural.md` for overall layering and structural concerns

### Step 4: Generate Report

Use the template in `report-template.md` to produce a structured markdown report.

Save the report to `./docs/review/YYYY-MM-DD-<project-name>-pattern-review.md` where:
- `YYYY-MM-DD` is today's date
- `<project-name>` is the project or repository name derived from the root directory name or `package.json`/`go.mod`/`Cargo.toml`

Example: `./docs/review/2026-04-17-my-service-pattern-review.md`

Create the `docs/review/` directory if it does not exist. Also output the report inline so the user can read it immediately without opening the file.

## Edge Cases

- **No recognizable language** — Proceed with language-agnostic review; note that language-specific considerations are unavailable
- **Monorepo / multi-language project** — Detect all languages; review each module in its own context
- **Very large codebase without `--scope`** — Sample key directories only; suggest the user re-run with `--scope` for deeper analysis of specific areas
- **Design doc but no code** — Pure design doc review; skip code analysis
- **No design docs and minimal code** — Brief assessment with pattern suggestions for as the project grows
- **Patterns already well-applied** — Acknowledge good usage; do not force unnecessary recommendations

## Scope Boundaries

This skill **does not**:
- Refactor code — it only recommends
- Enforce patterns dogmatically — it explains trade-offs
- Replace human architectural review — it is a first-pass automated check