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

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 and generated by the TypeScript resolver in 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 and rendered by helper functions in 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 (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 (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 around line 889 and generated by the generateItemExtraction function in 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 (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

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).

Running the /review Skill

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

# 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:

# 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:

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:

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:

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 and generated by 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 (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 (specifically lines 558-976 covering discovery through output formatting). The executable logic is generated by scripts/resolvers/review.ts, which contains functions like generatePlanFileDiscovery, generateItemExtraction, and generateVerificationDispatch that render the markdown steps into the skill's runtime flow.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}