plan-review

Files (1)

• SKILL.md

SKILL.md (first lines)

# Plan Review

**Announce at start:** "I'm using the plan-review skill to review this plan."

## When to Use

**ONLY** when the user explicitly requests plan review (e.g. "start plan review", "review the plan", "run plan review").

Do **not** auto-invoke after writing a plan. Do **not** substitute this for the self-review in `writing-plans`.

## Core Principle

**Under any circumstances, never skip even one subagent finding — including the stupidest ones.**

Every finding must be tracked, addressed in the plan, or explicitly pushed back with reasoning. No silent dismissals. No "that's obvious" shortcuts.

---

## Step 1: Decide Review Panel Size

| Complexity | Agents | When |
|------------|--------|------|
| **1** | 1 reviewer | Single file/area, small scope, low risk |
| **2** | 2 reviewers | Multiple files or subsystems, moderate risk |
| **3** | 3 reviewers | Cross-cutting change, new patterns, high risk, or many rules/skills involved |

When uncertain, prefer **more** reviewers over fewer.

---

## Step 2: Select Models

Use **different but comparable** models across reviewers. Resolve tier → model via the global main rule (`low-tier`, `medium-tier`, `high-tier`, `highest-tier`); do not hardcode model names here. At dispatch, pick an explicit slug from the Task tool's allowed list.

| Reviewer | Tier |
|----------|------|
| Reviewer 1 (always) | Same tier as the agent that wrote the plan |
| Reviewer 2 (if used) | `medium-tier` |
| Reviewer 3 (if used) | `low-tier` |

**Rules:**
- Reviewer 1: match the planner's tier; prefer a different model family when possible
- If reviewer 1 would be `high-tier` or `highest-tier`, ask first (global main rule) — requesting plan review alone does not authorize those tiers
- Reviewers must still differ from each other; never assign the same model to two reviewers
- Without permission, reviewers 2–3 stay on `medium-tier` / `low-tier` only

---

## Step 3: Prepare Context Packet

Build one shared context block. Attach the **full plan** (path or inline). Include:

```markdown
## Plan Review Context

### Business requirements
[What problem this solves, user-facing behavior, success criteria]

### Engineering requirements
[Constraints, non-functional reqs, compatibility, rollout, observability]

### Important input
[Spec excerpts, prior decisions, user preferences, known risks, open questions]

### Plan under review
Path: `[exact/path/to/plan.md]`
(or paste full plan if not saved yet)

### Scope summary
- Files/systems touched: [...]
- Estimated complexity: [low | medium | high]
- Why N reviewers: [1–3 sentence justification]
```

Do **not** dump full session history. Give reviewers what they need to evaluate the plan, not your reasoning process.

---

## Step 4: Dispatch Review Subagents

Launch **1–3 subagents in parallel** (one message, multiple `Subagent` calls). Use `subagent_type: "generalPurpose"` or a domain-specific type when clearly better (e.g. `security-reviewer`, `architect`, `code-reviewer`).

Each subagent prompt must include the context packet plus:

```markdown
You are Plan Reviewer [N] ([model name]). Review this implementation plan — do NOT implement it.

## Your job
1. **Scope & changes** — What will be created, modified, deleted? Missing files? Wrong boundaries?
2. **Rules** — Check ALL applicable rules:
   - User rules (global)
   - Project rules (`.cursor/rules/`, `AGENTS.md`, workspace rules)
   - Directory-scoped rules for every path the plan touches
3. **Skills & agents** — Identify every skill/subagent the plan should reference or invoke during execution (e.g. `preflight-unit-tests-check`, `review-security`, `preview-env-curl-testing`, `security-reviewer`). Flag missing or wrong ones.
4. **Plan quality** — Gaps vs requirements, placeholders/TBDs, task ordering, test strategy, rollback, edge cases.
5. **Risk** — What could go wrong? What's underspecified?

## Output format (required)

### Summary
[2–3 sentences]

### Findings
Number every finding. Use severity:

- 🔴 **Blocker** — Plan must change before execution
- 🟡 **Important** — Should fix; execution risk if ignored
- 🟢 **Minor** — Nice to fix; low risk

For each finding:
- **ID:** R[N]-F[number]  (e.g. R1-F3)
- **Severity:**
- **Category:** scope | rules | skills | testing | architecture | requirements | other
- **Finding:** [specific issue]
- **Evidence:** [quote plan section or rule/skill name]
- **Recommendation:** [concrete fix]

### Strengths
[What the plan does well]

From mister-gnommer/rules-of-engagement, MIT.

More from mister-gnommer/rules-of-engagement