---
name: ayf:plan-review
description: |
  Compound plan gate: CEO-scope check -> design sanity -> engineering review,
  each writing its own report, then a single human gate to proceed or abort.
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
  - Agent
  - AskUserQuestion
---

# /plan-review [N] -- Compound Plan Gate

Review a task plan through three stacked lenses -- **business**, then **design**,
then **engineering** -- writing one report per lens, then stop the human exactly
once with the consolidated concerns and a proceed/abort decision.

Where `/verify-plan` checks whether a plan is *internally consistent* (coverage,
atomicity, ordering...), `/plan-review` asks the questions that come *before* that:
are we building the right thing, is the experience sound, and will the engineering
hold up? The three phases run back-to-back with no interruption; the human decides
once, at Phase 4.

## Input

The human names the task to review by number: `/plan-review 42`.

If no number is given, use the currently locked task (`.ay/locks/` or
`.ay/tracking/locks/`), else the most recently modified folder under `.ay/plans/`.

## Step 0: Locate the plan (graceful abort)

Resolve the plan for task N. A plan is the folder `.ay/plans/task-{N}/` (or a
single plan file if that is the project's convention). Read, if present:
`README.md`, `context.md`, `files.md`, `sequence.md`, `tests.md`, `schema.md`,
plus the task file `.ay/tasks/task-{N}.md`, `.ay/tracking/DECISIONS.md`, and the
sprint goal at the top of `.ay/tracking/BOARD.md`.

**If no plan file/folder is found, abort gracefully** -- do not invent a plan and
do not run the phases. Print exactly this and stop:

```
/plan-review: no plan found for task {N}.

I looked in:
  .ay/plans/task-{N}/     (plan folder)
  .ay/tasks/task-{N}.md   (task definition)

To review a plan, provide one of:
  - Run /plan {N} first to generate .ay/plans/task-{N}/, then re-run /plan-review {N}
  - Or point me at an existing plan file:  /plan-review path/to/plan.md
```

Also create `.ay/reviews/` if it does not exist (the three phases write there).

---

## Phase 1 -- CEO-Scope Check (business)

Step out of the code. You are accountable to the business. Judge:

1. **Business value** -- Does the plan's goal deliver real value, or polish
   something nobody asked for? Quote the task's stated need next to the plan's goal.
2. **Market / user fit** -- Does this serve an actual user or sprint objective
   (top of BOARD.md)? Is now the right time, given this task's dependents?
3. **Scope & risk** -- Scope creep (speculative extras that widen blast radius)?
   Any conflict with a recorded decision in `DECISIONS.md` (cite the ADR heading)?

Write **`.ay/reviews/plan-review-ceo.md`**:

```markdown
# Plan Review -- Phase 1: CEO-Scope (Task {N})

**Verdict:** GREEN | YELLOW | RED

## Business value
{task-need vs plan-goal, quoted}

## Market / user fit
{who it serves; fit against the sprint goal + dependents}

## Scope & risk
{scope-creep items (keep/cut/defer); any DECISIONS.md conflict cited by ADR}

## Concerns (carried to the gate)
- {one line each, or "none"}
```

GREEN = right thing, tight scope. YELLOW = proceed-with-trims concerns. RED = wrong
problem or hard ADR conflict. A RED does **not** stop the flow -- record it and
continue; the human decides at Phase 4.

---

## Phase 2 -- Design Sanity (UX, flows, edge cases)

Assume the plan solves the right problem. Now judge the *experience and shape*:

1. **User flows** -- Do the flows the plan implies actually hang together end to
   end? Any dead ends, missing screens/states, or unclear entry/exit points?
2. **Edge & failure states** -- Are empty, loading, error, and boundary states
   accounted for, or only the happy path?
3. **Design coherence** -- Does it fit existing patterns/conventions (from
   `context.md` and the codebase), or invent a parallel way of doing something
   that already exists? Is there a materially simpler design?

Write **`.ay/reviews/plan-review-design.md`**:

```markdown
# Plan Review -- Phase 2: Design Sanity (Task {N})

**Verdict:** GREEN | YELLOW | RED

## User flows
{coherence end to end; dead ends / missing states}

## Edge & failure states
{empty / loading / error / boundary coverage; gaps}

## Design coherence
{fits existing patterns? simpler alternative?}

## Concerns (carried to the gate)
- {one line each, or "none"}
```

---

## Phase 3 -- Engineering Review (architecture, complexity, deps)

Now the build itself. Review `sequence.md`, `files.md`, `schema.md`,
`api-reference.md`:

1. **Architecture** -- Sound boundaries and ownership? No two files owning the
   same responsibility; no leaky abstractions?
2. **Complexity** -- Is each step atomic and buildable in dependency order (no
   step needs a later step's output)? Any step doing too much?
3. **Dependencies** -- New deps justified and pinned? External API signatures
   real (verified via docs/`opensrc`, not guessed)? Hidden coupling or circular
   deps? Top execution risks ranked.

Fold in `/verify-plan`'s 8-dimension check for the mechanical half rather than
restating it; summarize its PASS/FAIL grid here.

Write **`.ay/reviews/plan-review-eng.md`**:

```markdown
# Plan Review -- Phase 3: Engineering (Task {N})

**Verdict:** GREEN | YELLOW | RED

## Architecture
{boundaries, ownership, coherence}

## Complexity
{atomicity, ordering, over-large steps}

## Dependencies
{new deps, API fidelity, coupling; /verify-plan grid summary}

## Top execution risks
1. {risk} -- {mitigation}

## Concerns (carried to the gate)
- {one line each, or "none"}
```

---

## Phase 4 -- Single Human Gate

This is the one and only stop. Combine the three verdicts -- the **worst** phase
caps the overall (one RED => overall REJECT; any YELLOW, no RED => REVISE; all
GREEN => APPROVE). Print the consolidated view:

```
PLAN REVIEW -- Task {N}: {title}
================================
  1. CEO-scope (business):        {GREEN/YELLOW/RED}  {one-line reason}
  2. Design sanity (UX/flows):    {GREEN/YELLOW/RED}  {one-line reason}
  3. Engineering (arch/complexity): {GREEN/YELLOW/RED}  {one-line reason}

Overall: {APPROVE / REVISE / REJECT}

Consolidated concerns:
  [CEO]    {concern}            (or "none")
  [design] {concern}
  [eng]    {concern}

Reports:
  .ay/reviews/plan-review-ceo.md
  .ay/reviews/plan-review-design.md
  .ay/reviews/plan-review-eng.md
```

Then ask with `AskUserQuestion`:

**"Plan review complete -- overall {verdict}. Proceed with the build, or abort?"**

- **Proceed** -- greenlight; hand off to `/task-start {N}` or `/go`. (Offer even on
  REVISE if the human accepts the noted trade-offs.)
- **Abort** -- send the plan back to `/plan {N}` to address the concerns, then the
  human can re-run `/plan-review {N}`.

Do not auto-edit the plan and do not start building. The human's answer here is the
only authorization to move forward.

## Notes

- **Why one gate:** each phase is a filter, but interrupting three times is
  friction. The phases run to completion so the human sees business, design, and
  engineering in a single proceed/abort decision.
- **RED never short-circuits:** a RED in an earlier phase still runs the later
  phases, so the human gets the complete diagnosis at the gate.
- **Artifacts persist:** the three `.ay/reviews/plan-review-*.md` files remain as
  the decision record for why the task was (or was not) greenlit.
- **Relationship to `/verify-plan`:** that command is the mechanical consistency
  check and lives inside Phase 3; `/plan-review` wraps it with business and design
  judgment.