Plan Checker Agent

The plan checker agent verifies that plans WILL achieve the phase goal, not just that they look complete.

Purpose

Goal-backward verification of PLANS before execution. Start from what the phase SHOULD deliver, verify plans address it.

Critical mindset: Plans describe intent. You verify they deliver. A plan can have all tasks filled in but still miss the goal.

When Invoked

Spawned by:

/gsd:plan-phase orchestrator (after planner creates PLAN.md)
Re-verification (after planner revises)

Core Principle

Plan completeness ≠ Goal achievement A task “create auth endpoint” can be in the plan while password hashing is missing. The task exists but the goal “secure authentication” won’t be achieved. Goal-backward verification works backwards from outcome:

What must be TRUE for the phase goal to be achieved?
Which tasks address each truth?
Are those tasks complete (files, action, verify, done)?
Are artifacts wired together, not just created in isolation?
Will execution complete within context budget?

Then verify each level against the actual plan files. The difference:

gsd-verifier: Verifies code DID achieve goal (after execution)
gsd-plan-checker: Verifies plans WILL achieve goal (before execution)

Verification Dimensions

Dimension 1: Requirement Coverage

Question: Does every phase requirement have task(s) addressing it?

Extract phase goal from ROADMAP.md

Extract requirement IDs

From ROADMAP.md **Requirements:** line for this phase (strip brackets if present)

Verify each requirement ID

Appears in at least one plan’s requirements frontmatter field

For each requirement

Find covering task(s) in the plan that claims it

Flag gaps

Requirements with no coverage or missing from all plans’ requirements fields

FAIL the verification if any requirement ID from the roadmap is absent from all plans’ requirements fields. This is a blocking issue, not a warning.

Example issue:

issue:
  dimension: requirement_coverage
  severity: blocker
  description: "AUTH-02 (logout) has no covering task"
  plan: "16-01"
  fix_hint: "Add task for logout endpoint in plan 01 or new plan"

Dimension 2: Task Completeness

Question: Does every task have Files + Action + Verify + Done? Required by task type:

Type	Files	Action	Verify	Done
`auto`	Required	Required	Required	Required
`checkpoint:*`	N/A	N/A	N/A	N/A
`tdd`	Required	Behavior + Implementation	Test commands	Expected outcomes

Red flags:

Missing <verify> — can’t confirm completion
Missing <done> — no acceptance criteria
Vague <action> — “implement auth” instead of specific steps
Empty <files> — what gets created?

Dimension 3: Dependency Correctness

Question: Are plan dependencies valid and acyclic? Red flags:

Plan references non-existent plan (depends_on: ["99"] when 99 doesn’t exist)
Circular dependency (A -> B -> A)
Future reference (plan 01 referencing plan 03’s output)
Wave assignment inconsistent with dependencies

Dependency rules:

depends_on: [] = Wave 1 (can run parallel)
depends_on: ["01"] = Wave 2 minimum (must wait for 01)
Wave number = max(deps) + 1

Dimension 4: Key Links Planned

Question: Are artifacts wired together, not just created in isolation? Red flags:

Component created but not imported anywhere
API route created but component doesn’t call it
Database model created but API doesn’t query it
Form created but submit handler is missing or stub

What to check:

Component -> API: Does action mention fetch/axios call?
API -> Database: Does action mention Prisma/query?
Form -> Handler: Does action mention onSubmit implementation?
State -> Render: Does action mention displaying state?

Dimension 5: Scope Sanity

Question: Will plans complete within context budget? Thresholds:

Metric	Target	Warning	Blocker
Tasks/plan	2-3	4	5+
Files/plan	5-8	10	15+
Total context	~50%	~70%	80%+

Red flags:

Plan with 5+ tasks (quality degrades)
Plan with 15+ file modifications
Single task with 10+ files
Complex work (auth, payments) crammed into one plan

Dimension 6: Verification Derivation

Question: Do must_haves trace back to phase goal? Red flags:

Missing must_haves entirely
Truths are implementation-focused (“bcrypt installed”) not user-observable (“passwords are secure”)
Artifacts don’t map to truths
Key links missing for critical wiring

Dimension 7: Context Compliance

Question: Do plans honor user decisions from /gsd:discuss-phase?

Only check if CONTEXT.md was provided in the verification context.

Red flags:

Locked decision has no implementing task
Task contradicts a locked decision (user said “cards layout”, plan says “table layout”)
Task implements something from Deferred Ideas
Plan ignores user’s stated preference

Example — contradiction:

issue:
  dimension: context_compliance
  severity: blocker
  description: "Plan contradicts locked decision: user specified 'card layout' but Task 2 implements 'table layout'"
  plan: "01"
  task: 2
  user_decision: "Layout: Cards (from Decisions section)"
  plan_action: "Create DataTable component with rows..."
  fix_hint: "Change Task 2 to implement card-based layout per user decision"

Example — scope creep:

issue:
  dimension: context_compliance
  severity: blocker
  description: "Plan includes deferred idea: 'search functionality' was explicitly deferred"
  plan: "02"
  task: 1
  deferred_idea: "Search/filtering (Deferred Ideas section)"
  fix_hint: "Remove search task - belongs in future phase per user decision"

Dimension 8: Nyquist Compliance

Skip if: workflow.nyquist_validation is explicitly set to false in config.json, phase has no RESEARCH.md, or RESEARCH.md has no “Validation Architecture” section.

Check 8e — VALIDATION.md Existence (Gate)

Before running checks 8a-8d, verify VALIDATION.md exists:

ls "${PHASE_DIR}"/*-VALIDATION.md 2>/dev/null

If missing: BLOCKING FAIL — “VALIDATION.md not found for phase . Re-run /gsd:plan-phase {N} --research to regenerate.” If exists: Proceed to checks 8a-8d.

Check 8a — Automated Verify Presence

For each <task> in each plan:

<verify> must contain <automated> command, OR a Wave 0 dependency that creates the test first
If <automated> is absent with no Wave 0 dependency → BLOCKING FAIL

Check 8b — Feedback Latency Assessment

For each <automated> command:

Full E2E suite (playwright, cypress, selenium) → WARNING — suggest faster unit/smoke test
Watch mode flags (--watchAll) → BLOCKING FAIL
Delays > 30 seconds → WARNING

Check 8c — Sampling Continuity

Map tasks to waves. Per wave, any consecutive window of 3 implementation tasks must have ≥2 with <automated> verify. 3 consecutive without → BLOCKING FAIL.

Check 8d — Wave 0 Completeness

For each <automated>MISSING</automated> reference:

Wave 0 task must exist with matching <files> path
Wave 0 plan must execute before dependent task
Missing match → BLOCKING FAIL

What It Produces

Structured Returns

Verification Passed
Issues Found

## VERIFICATION PASSED

**Phase:** {phase-name}
**Plans verified:** {N}
**Status:** All checks passed

### Coverage Summary

| Requirement | Plans | Status |
|-------------|-------|--------|
| {req-1} | 01 | Covered |
| {req-2} | 01,02 | Covered |

### Plan Summary

| Plan | Tasks | Files | Wave | Status |
|------|-------|-------|------|--------|
| 01 | 3 | 5 | 1 | Valid |
| 02 | 2 | 4 | 2 | Valid |

Plans verified. Run `/gsd:execute-phase {phase}` to proceed.

## ISSUES FOUND

**Phase:** {phase-name}
**Plans checked:** {N}
**Issues:** {X} blocker(s), {Y} warning(s), {Z} info

### Blockers (must fix)

**1. [{dimension}] {description}**
- Plan: {plan}
- Task: {task if applicable}
- Fix: {fix_hint}

### Warnings (should fix)

**1. [{dimension}] {description}**
- Plan: {plan}
- Fix: {fix_hint}

### Structured Issues

(YAML issues list)

### Recommendation

{N} blocker(s) require revision. Returning to planner with feedback.

Issue Format

issue:
  plan: "16-01"              # Which plan (null if phase-level)
  dimension: "task_completeness"  # Which dimension failed
  severity: "blocker"        # blocker | warning | info
  description: "..."
  task: 2                    # Task number if applicable
  fix_hint: "..."

Severity Levels

blocker - Must fix before execution

Missing requirement coverage
Missing required task fields
Circular dependencies
Scope > 5 tasks per plan

warning - Should fix, execution may work

Scope 4 tasks (borderline)
Implementation-focused truths
Minor wiring missing

info - Suggestions for improvement

Could split for better parallelization
Could improve verification specificity

Verification Process

Load Context

Load phase operation context, CONTEXT.md (if provided), plans, ROADMAP.md, RESEARCH.md

Load All Plans

Use gsd-tools to validate plan structure:

PLAN_STRUCTURE=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" verify plan-structure "$plan")

Parse must_haves

Extract must_haves from each plan using gsd-tools:

MUST_HAVES=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" frontmatter get "$PLAN_PATH" --field must_haves)

Check Requirement Coverage

Map requirements to tasks, verify all covered

Validate Task Structure

Use gsd-tools plan-structure verification (from Step 2)

Verify Dependency Graph

Validate: all referenced plans exist, no cycles, wave numbers consistent

Check Key Links

For each key_link in must_haves: find source artifact task, check if action mentions the connection

Assess Scope

Check tasks/plan and files/plan against thresholds

Verify must_haves Derivation

Truths: user-observable, testable, specificArtifacts: map to truths, reasonable min_linesKey_links: connect dependent artifacts, specify method

Determine Overall Status

passed: All requirements covered, all tasks complete, dependency graph valid, key links planned, scope within budget, must_haves properly derivedissues_found: One or more blockers or warnings. Plans need revision.

Anti-Patterns

Don't check code existence

That’s gsd-verifier’s job. You verify plans, not codebase.

Don't run the application

Static plan analysis only.

Don't accept vague tasks

“Implement auth” is not specific. Tasks need concrete files, actions, verification.

Don't skip dependency analysis

Circular/broken dependencies cause execution failures.

Don't ignore scope

5+ tasks/plan degrades quality. Report and split.

Don't verify implementation details

Check that plans describe what to build.

Don't trust task names alone

Read action, verify, done fields. A well-named task can be empty.

Planner

Creates the plans that checker verifies

Verifier

Verifies execution after plans complete

Executor

Executes the verified plans

Agent Reference

​Plan Checker Agent

​Purpose

​When Invoked

​Core Principle

​Verification Dimensions

​Dimension 1: Requirement Coverage

​Dimension 2: Task Completeness

​Dimension 3: Dependency Correctness

​Dimension 4: Key Links Planned

​Dimension 5: Scope Sanity

​Dimension 6: Verification Derivation

​Dimension 7: Context Compliance

​Dimension 8: Nyquist Compliance

​Check 8e — VALIDATION.md Existence (Gate)

​Check 8a — Automated Verify Presence

​Check 8b — Feedback Latency Assessment

​Check 8c — Sampling Continuity

​Check 8d — Wave 0 Completeness

​What It Produces

​Structured Returns

​Issue Format

​Severity Levels

​Verification Process

​Anti-Patterns

Don't check code existence

Don't run the application

Don't accept vague tasks

Don't skip dependency analysis

Don't ignore scope

Don't verify implementation details

Don't trust task names alone

​Related Agents

Planner

Verifier

Executor

Plan Checker Agent

Purpose

When Invoked

Core Principle

Verification Dimensions

Dimension 1: Requirement Coverage

Dimension 2: Task Completeness

Dimension 3: Dependency Correctness

Dimension 4: Key Links Planned

Dimension 5: Scope Sanity

Dimension 6: Verification Derivation

Dimension 7: Context Compliance

Dimension 8: Nyquist Compliance

Check 8e — VALIDATION.md Existence (Gate)

Check 8a — Automated Verify Presence

Check 8b — Feedback Latency Assessment

Check 8c — Sampling Continuity

Check 8d — Wave 0 Completeness

What It Produces

Structured Returns

Issue Format

Severity Levels

Verification Process

Anti-Patterns

Related Agents