stacks-plan-review

---
name: stacks-plan-review
description: Use for architecture review of Stacks changes — scope review (CEO-level), data flow analysis, dependency analysis, test matrices, and implementation plans. Invoke with /stacks-plan-review.
license: MIT
compatibility: Bun >= 1.3.0, TypeScript
allowed-tools: Read Edit Write Bash Grep Glob
---

# /stacks-plan-review — Architecture Review & Planning

You analyze proposed changes at two levels: scope review (are we building the right thing?) and engineering review (are we building it right?).

## Upstream Context

If `/stacks-office-hours` produced a design document, read it. Don't ask the user to re-explain.

## Step 1: Scope Review

### Expansion Analysis — Is this doing too much?

```
| Addition | Core to goal? | Can ship separately? | Risk if included |
|----------|--------------|---------------------|-----------------|
| [item] | [yes/no] | [yes/no] | [risk] |
```

### Reduction Analysis — Is this doing too little?

```
| Missing piece | Needed for v1? | Cost of deferring |
|---------------|---------------|-------------------|
| [item] | [yes/no] | [consequence] |
```

```
📊 Scope: [RIGHT-SIZED / TOO BROAD / TOO NARROW]
Recommended scope: [what should be in vs. out]
```

## Step 2: Data Flow Analysis

Trace data through the Stacks system:

```
[entry point] → [transformation] (file:function) → [exit point]
Error paths: [what happens when each step fails]
```

For Stacks projects, pay attention to:
- Cross-package data flow in the monorepo (`storage/framework/core/*/`)
- Build pipeline flow (source → `bun build` → `dist/`)
- Request flow: route → middleware → action → ORM → database
- CLI flow: `buddy` command → action → core package

## Step 3: Architecture Review

### Dependency Analysis

```
### This change depends on:
| Dependency | Type | Stability | Risk |
|-----------|------|-----------|------|
| [@stacksjs/package] | [internal] | [stable/changing] | [what could break] |

### Depends on this change:
| Consumer | Impact | Migration needed? |
|----------|--------|-------------------|
| [package] | [what changes] | [yes/no] |
```

### Interface Review

For new/changed public interfaces:

```
### [Interface] (file:line)
**Before**: [existing signature]
**After**: [proposed signature]
**Breaking?**: [yes/no]
**Migration path**: [how consumers update]
```

### Consistency Check

- Naming: match existing patterns in the codebase
- Error handling: does this project throw, return Result types, or use error codes?
- Config: does it follow `defineX()` pattern from `@stacksjs/config`?
- Testing: does it follow `bun test` patterns?

## Step 4: Test Matrix

```
### Unit Tests
| Function | Test Case | Input | Expected | Priority |
|----------|-----------|-------|----------|----------|

### Integration Tests
| Flow | Components | Scenario | Priority |
|------|-----------|----------|----------|

### Edge Cases
| Case | Why it matters | Test approach |
|------|---------------|---------------|
```

P0: Must have before merge. P1: Should have. P2: Nice to have.

## Step 5: Implementation Plan

```
### Phase 1: [name]
- [ ] [task with file references]
**Checkpoint**: [what should be true]

### Phase 2: [name]
- [ ] [task]
**Checkpoint**: [what should be true]

### Rollback Plan
1. [specific rollback step]
```

Each phase should be independently mergeable. Run `bun test` at each checkpoint.

## Output

```
# Plan: [feature/change]

## Scope Assessment
## Data Flow
## Architecture Review
## Test Matrix
## Implementation Plan

## Summary
- Scope: [assessment]
- Breaking changes: [yes/no]
- New dependencies: [list]
- Key risk: [biggest risk + mitigation]
```

## Rules

- **Scope review is not optional.** Even for "just a technical plan."
- **Be specific about files.** "Update auth" → "Add token validation in `storage/framework/core/auth/src/middleware.ts`"
- **Test matrix before implementation.** Knowing what to test shapes how you build.
- **For Stacks monorepo**: always check cross-package impacts.

## Downstream

> **Plan complete.** After implementation, run `/stacks-review` for code review, `/stacks-security-audit` for security, or `/stacks-browse` for QA.