# How the gstack /review Skill Verifies Plan Completion Against a Diff

> Learn how the gstack /review skill verifies plan completion against a git diff. It checks actionable items against your code changes for accurate status updates.

- Repository: [Garry Tan/gstack](https://github.com/garrytan/gstack)
- Tags: how-to-guide
- Published: 2026-05-15

---

**The `/review` skill verifies plan completion by discovering the plan file, extracting actionable items, classifying them by verification mode, and cross-referencing each item against the current `git diff` to mark them as DONE, PARTIAL, NOT DONE, or UNVERIFIABLE.**

The `garrytan/gstack` repository provides a sophisticated pre-landing PR review system that ensures code changes actually fulfill the requirements outlined in engineering plans. The verification pipeline is implemented in [`review/SKILL.md`](https://github.com/garrytan/gstack/blob/main/review/SKILL.md) and generated by the TypeScript resolver in [`scripts/resolvers/review.ts`](https://github.com/garrytan/gstack/blob/main/scripts/resolvers/review.ts), creating a seamless bridge between planning documents and actual code changes.

## The Four-Stage Verification Pipeline

The `/review` skill executes a tightly coupled four-stage pipeline to audit plan completion. Each stage is defined in [`review/SKILL.md`](https://github.com/garrytan/gstack/blob/main/review/SKILL.md) and rendered by helper functions in [`scripts/resolvers/review.ts`](https://github.com/garrytan/gstack/blob/main/scripts/resolvers/review.ts).

### Stage 1: Plan File Discovery

The skill begins by locating the relevant plan file. It first checks for a plan file referenced in the conversation context. If none is found, it executes a content-based search across typical plan locations including `$HOME/.gstack/projects/*`, `$HOME/.claude/plans`, and `.gstack/plans`.

According to the source code in [`review/SKILL.md`](https://github.com/garrytan/gstack/blob/main/review/SKILL.md) (around line 558), the discovery process prints either `PLAN_FILE: <path>` or `NO_PLAN_FILE` to indicate success or failure. The `generatePlanFileDiscovery` function in [`scripts/resolvers/review.ts`](https://github.com/garrytan/gstack/blob/main/scripts/resolvers/review.ts) (around line 560) injects this logic into the skill execution flow.

### Stage 2: Actionable Item Extraction

Once the plan file is located, the skill parses the first 20 lines to confirm relevance, then extracts every actionable item including checkboxes, numbered steps, imperative statements, file specifications, and test requirements.

The extraction caps at 50 items and tags each with a high-level category:
- **CODE** – Implementation changes
- **TEST** – Test coverage requirements  
- **MIGRATION** – Database or schema changes
- **CONFIG** – Configuration updates
- **DOCS** – Documentation changes

This logic is implemented in [`review/SKILL.md`](https://github.com/garrytan/gstack/blob/main/review/SKILL.md) around line 889 and generated by the `generateItemExtraction` function in [`scripts/resolvers/review.ts`](https://github.com/garrytan/gstack/blob/main/scripts/resolvers/review.ts).

### Stage 3: Verification Mode Classification

For each extracted item, the skill assigns a verification mode that determines how completion will be validated. The classification rules appear in [`review/SKILL.md`](https://github.com/garrytan/gstack/blob/main/review/SKILL.md) (lines 917-941) and include four distinct modes:

- **DIFF-VERIFIABLE** – Changes that must appear in `git diff` (source code, tests)
- **CROSS-REPO** – Files living in sibling repositories verified via filesystem checks
- **EXTERNAL-STATE** – Resources outside the repo (Cloudflare DNS, Supabase, AWS) marked as unverifiable
- **CONTENT-SHAPE** – Files requiring convention validation via `validate-*` scripts in [`package.json`](https://github.com/garrytan/gstack/blob/main/package.json)

The `generateVerificationDispatch` function handles the logic for routing items into these categories.

### Stage 4: Cross-Reference Against the Diff

The final stage executes the verification by running `git diff origin/<base>...HEAD` (plus `git log` for context) and dispatching each item through the appropriate verification method:

- **DIFF-VERIFIABLE** items are matched against paths in the diff output
- **CROSS-REPO** items use `[ -f <path> ]` filesystem checks
- **EXTERNAL-STATE** items are immediately marked **UNVERIFIABLE** with manual-check notes
- **CONTENT-SHAPE** items run validator scripts; passing results upgrade the status to **DONE**

The skill classifies results into five statuses: **DONE**, **PARTIAL**, **NOT DONE**, **CHANGED**, or **UNVERIFIABLE**. The final audit renders as a structured markdown table under the `PLAN COMPLETION AUDIT` heading (lines 954-976 in [`review/SKILL.md`](https://github.com/garrytan/gstack/blob/main/review/SKILL.md)).

## Running the /review Skill

To verify plan completion against your current branch diff, execute the skill from your repository root:

```bash

# Ensure you are on your feature branch

~/.claude/skills/gstack/bin/gstack review

```

The skill automatically:
1. Detects the base branch (typically `main`)
2. Locates the plan file using the discovery algorithm
3. Extracts and classifies actionable items
4. Cross-references the current `git diff` against the plan
5. Emits the completion audit report

### Example Plan File Structure

The skill recognizes actionable items in standard markdown formats:

```markdown

# Feature XYZ Implementation

- [ ] Add UserService authentication module (CODE)
- [ ] Write unit tests for UserService (TEST)
- [ ] Create users table migration (MIGRATION)
- [ ] Update Cloudflare DNS for api.example.com (EXTERNAL-STATE)
- [ ] Add API documentation to README (DOCS)

```

### Sample Audit Output

After processing, the skill generates a structured completion report:

```markdown
PLAN COMPLETION AUDIT
═══════════════════════════════
Plan: /home/dev/.gstack/projects/app/feature-xyz.md

## Implementation Items

  [DONE]      Add UserService — src/services/user_service.rb (+142 lines)
  [UNVERIFIABLE] Update Cloudflare DNS — external system, manual check required

## Test Items  

  [DONE]      Write unit tests — test/services/user_service_test.rb

## Migration Items

  [DONE]      Create users table — db/migrate/20240315_create_users.rb

────────────────────────────────
COMPLETION: 3/4 DONE, 1 UNVERIFIABLE
────────────────────────────────

```

## How Verification Modes Map to Git Operations

The `DIFF-VERIFIABLE` classification triggers the core verification logic. The resolver effectively executes:

```bash
git diff origin/main...HEAD --stat | grep 'src/services/user_service.rb'

```

When the diff contains matching file paths, the associated plan item receives **DONE** status. For `CONTENT-SHAPE` items, the resolver additionally executes:

```bash
npm run validate-api-schema  # Example validator script

```

If the validator exits with code 0, the item upgrades from `NOT DONE` to `DONE`.

## Summary

- The `/review` skill implements a four-stage pipeline (Discovery, Extraction, Classification, Cross-Reference) defined in [`review/SKILL.md`](https://github.com/garrytan/gstack/blob/main/review/SKILL.md) and generated by [`scripts/resolvers/review.ts`](https://github.com/garrytan/gstack/blob/main/scripts/resolvers/review.ts).
- **Verification modes** (DIFF-VERIFIABLE, CROSS-REPO, EXTERNAL-STATE, CONTENT-SHAPE) determine whether an item is checked against `git diff`, filesystem state, external APIs, or validation scripts.
- Items receive statuses of **DONE**, **PARTIAL**, **NOT DONE**, **CHANGED**, or **UNVERIFIABLE** based on evidence found in `git diff origin/<base>...HEAD` and related checks.
- The audit output appears under the `PLAN COMPLETION AUDIT` heading with per-category tallies and overall completion metrics.

## Frequently Asked Questions

### How does the skill handle plan files stored outside the repository?

The skill searches standard locations including `$HOME/.gstack/projects/*`, `$HOME/.claude/plans`, and `.gstack/plans` within the repository. If a plan file exists in a sibling repository (CROSS-REPO mode), the skill uses filesystem checks `[ -f <path> ]` rather than `git diff` to verify completion.

### What happens if a plan contains tasks for external services like DNS or cloud infrastructure?

Items classified as **EXTERNAL-STATE** are automatically marked **UNVERIFIABLE** with a note indicating manual verification is required. The skill does not attempt to query live systems; instead, it flags these items in the audit output for human review.

### Can the skill validate that code follows specific architectural patterns?

Yes. Items tagged as **CONTENT-SHAPE** trigger validation scripts defined in [`package.json`](https://github.com/garrytan/gstack/blob/main/package.json) (any script prefixed with `validate-`). If the validator passes, the item status upgrades to **DONE**. This allows automated verification of API schemas, linting rules, or custom architecture constraints beyond simple file existence.

### Where is the verification logic actually implemented?

The human-readable workflow definitions reside in [`review/SKILL.md`](https://github.com/garrytan/gstack/blob/main/review/SKILL.md) (specifically lines 558-976 covering discovery through output formatting). The executable logic is generated by [`scripts/resolvers/review.ts`](https://github.com/garrytan/gstack/blob/main/scripts/resolvers/review.ts), which contains functions like `generatePlanFileDiscovery`, `generateItemExtraction`, and `generateVerificationDispatch` that render the markdown steps into the skill's runtime flow.