# Review Plan

> Read-only audit of a finished (or near-finished) plan suite. Compares the suite's index.md goal and per-chunk acceptance criteria against the actual git diff since the suite was created, and reports goal alignment, coverage gaps, drift (changes not traceable to any chunk), and status-sanity issues (chunks marked done whose criteria don't appear satisfied). Use when the user invokes /review-plan,…

- **Type:** Skill
- **Install:** `agentstack add skill-vpaivag-skills-review-plan`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [vpaivag](https://agentstack.voostack.com/s/vpaivag)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [vpaivag](https://github.com/vpaivag)
- **Source:** https://github.com/vpaivag/skills/tree/main/skills/review-plan

## Install

```sh
agentstack add skill-vpaivag-skills-review-plan
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# /review-plan

Audit a plan suite produced by `/deep-plan` against the work that's actually landed in the codebase. Answer: **did the diff deliver what the plan promised, and is the suite's recorded status honest?**

`plan-tracker` shows what the suite *says*. `review-plan` checks whether the suite is *telling the truth*.

## Operating mode

**Strictly read-only.** Use only `Read`, `Glob`, `Grep`, and read-only `Bash` (`ls`, `find`, `cat`, `git log`, `git diff`, `git show`, `git status`). Never edit the suite, the chunk files, or the code. Never update statuses or commit. The output is one report printed to the conversation.

## Usage

`/review-plan` (with optional path to a suite directory or `index.md`).

A *suite* is any directory under the plans directory (resolved from `.claude/plans-config.json` → `plansDir`, default `.claude/plans`) containing an `index.md`. Single-chunk suites are reviewed identically to multi-chunk ones.

If no path is given, discover suites under the plans directory and use the only one. If multiple, call `AskUserQuestion` with up to 4 most-recently-modified suites. If `AskUserQuestion` is unavailable, fall back to plain text: print the candidate suites as a numbered list (most-recently-modified first) and wait for the user to reply with a number or path.

## Phases

### Phase 1 — Read the suite

Read `index.md` (suite name, goal, chunk table) and every chunk file it references (frontmatter status, `Files Changed`, `Acceptance Criteria`).

If the index lists a chunk file that doesn't exist, or a chunk file is malformed (missing required sections per `PLAN-FORMAT.md`), record it as a **structural** finding and continue — don't bail.

If the index status and the chunk-frontmatter status disagree for any chunk, flag it as a status-sanity issue.

### Phase 2 — Determine the diff baseline

Try in order, and state which one you used in the report:

1. **Creation commit.** `git log --diff-filter=A --follow --format=%H -- /index.md | tail -1`. Use that commit's parent as baseline. If `index.md` is uncommitted, baseline is `HEAD` and include uncommitted state via `git status --porcelain` + `git diff`.
2. **Timestamp fallback.** If git log is empty, parse the suite directory's `YYYY-MM-DD-HHMMSS-...` prefix and use `git rev-list -1 --before="" HEAD`.
3. **No git repo.** Stop and tell the user this skill needs git history; suggest manual chunk-by-chunk verification instead.

Collect the file list with `git diff --name-status ..HEAD`. Read targeted hunks (`git diff ..HEAD -- `) when verifying a specific criterion — don't dump the whole diff into context.

Exclude the suite directory itself (`//**`, where `` is the resolved plans directory) from the drift bucket — suite metadata isn't deliverable code.

### Phase 3 — Cross-check

Build four findings buckets.

**A. Goal alignment.** Read the suite goal. Look at the shape of the diff (which directories, which subsystems). In 2–4 sentences: does the diff plausibly deliver the goal? Be specific — cite files. Note anything the goal implies that you can't see.

**B. Coverage.** For each chunk, walk its `Files Changed` and `Acceptance Criteria`:
- Is each declared file in the diff?
- Is each criterion plausibly satisfied? Spot-check the relevant hunks. If a criterion specifies an interface (function, type, schema field, route, env var), grep for it.

You're not running tests. If a criterion needs runtime verification ("deploys cleanly to staging"), mark it **unverifiable from diff**.

**C. Drift.** For each non-suite file in the diff, ask which chunk's `Files Changed` covers it. If none, group as **plausibly related** (incidental cleanup tied to a chunk) or **unrelated / scope creep**. When in doubt, list it and let the user judge — drift is observation, not accusation.

**D. Status sanity.** For each chunk:
- Recorded `done` → criteria plausibly satisfied and files changed? If not, flag.
- Recorded `pending`/`in-progress` → diff already contains its files / satisfies its criteria? If yes, the recorded status lags reality — flag.
- Recorded `blocked` → note it; not necessarily an issue.
- Index vs. chunk-frontmatter mismatch → flag (from Phase 1).

### Phase 4 — Report

Print one report:

```
🔎 Plan review: 
   Path: 
   Baseline:  ()
   Diff:  files changed, excluding suite dir
   Recorded status: / chunks done

## Goal alignment

Verdict: ✅ aligned | ⚠️ partial | ❌ off-target

## Coverage gaps
- [chunk-name]  — 

## Drift
Plausibly related:
- :  — likely tied to 

Unrelated / scope creep:
- :  — no chunk claims this

## Status sanity
- : recorded , but  → suggest 

## Structural issues

## Bottom line

```

End your turn after printing. Do not offer to fix anything, update statuses, or suggest commits — the user owns those decisions.

## Why each rule exists

- **Empty buckets are good.** Don't pad. If coverage is clean, say so in one line.
- **Every finding cites a chunk, file, or criterion.** "Looks incomplete" is not a finding.
- **State the baseline explicitly.** A wrong comparison window invalidates the whole report; the user needs to sanity-check it.
- **Mark runtime-only criteria unverifiable.** Don't pretend a code read can confirm "deploys cleanly".

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [vpaivag](https://github.com/vpaivag)
- **Source:** [vpaivag/skills](https://github.com/vpaivag/skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-vpaivag-skills-review-plan
- Seller: https://agentstack.voostack.com/s/vpaivag
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.