Files
msd-core/.planning/phases/16-plan-verification-loop/16-01-PLAN.md
Lex Christopherson 96cd23c750 docs(16): create phase plan
Phase 16: Plan Verification Loop
- 3 plan(s) in 2 wave(s)
- Wave 1: 16-01 (create gsd-plan-checker agent)
- Wave 2: 16-02, 16-03 (parallel - orchestrator + planner revision)
- Ready for execution

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-16 08:52:31 -06:00

6.8 KiB

phase, plan, type, wave, depends_on, files_modified, autonomous, must_haves
phase plan type wave depends_on files_modified autonomous must_haves
16-plan-verification-loop 01 execute 1
agents/gsd-plan-checker.md
true
truths artifacts key_links
Plan checker can load PLAN.md files and parse frontmatter
Plan checker can verify plans against phase goal from ROADMAP.md
Plan checker returns structured issues or passed status
Checker output is consumable by orchestrator and planner
path provides min_lines
agents/gsd-plan-checker.md Plan verification expertise and structured issue reporting 400
from to via
gsd-plan-checker PLAN.md frontmatter must_haves, depends_on, files_modified parsing
from to via
gsd-plan-checker ROADMAP.md phase goal extraction
Create gsd-plan-checker agent with goal-backward plan verification expertise.

Purpose: Enable plan validation before execution. The checker reads PLAN.md files, verifies they will achieve the phase goal, and returns structured issues or passed status.

Output: agents/gsd-plan-checker.md (~400-600 lines)

<execution_context> @/.claude/get-shit-done/workflows/execute-plan.md @/.claude/get-shit-done/templates/summary.md </execution_context>

@.planning/PROJECT.md @.planning/ROADMAP.md @.planning/STATE.md

Existing agents to follow pattern: @agents/gsd-verifier.md @agents/gsd-planner.md

Phase brief with design decisions: @.planning/phases/16-plan-verification-loop/16-BRIEF.md

Task 1: Create gsd-plan-checker agent file agents/gsd-plan-checker.md Create agents/gsd-plan-checker.md following gsd-verifier pattern (checker role, not doer).

Frontmatter:

---
name: gsd-plan-checker
description: Verifies plans will achieve phase goal before execution. Goal-backward analysis of plan quality. Spawned by /gsd:plan-phase orchestrator.
tools: Read, Bash, Glob, Grep
color: green
---

Structure (~400-600 lines total):

  1. <role> (~30 lines)

    • Plan quality verifier role
    • Spawned by /gsd:plan-phase orchestrator
    • Returns structured issues or passed status
    • Critical mindset: Plans describe intent, verify they deliver
  2. <core_principle> (~40 lines)

    • "Plan completeness ≠ Goal achievement"
    • Goal-backward verification of PLANS not code
    • Start from phase goal, verify plans address it
  3. <verification_dimensions> (~150 lines) Six dimensions from BRIEF:

    • Requirement coverage — Every phase requirement has task(s) addressing it
    • Task completeness — Every task has Files + Action + Verify + Done
    • Dependency correctness — Nothing references future work, depends_on valid
    • Key links planned — Not just artifacts, but wiring between them
    • Scope sanity — Plans within context budget (~50%), 2-3 tasks each
    • Verification derivation — must_haves trace back to phase goal
  4. <verification_process> (~150 lines) Step-by-step process:

    • Step 1: Load context (phase goal, requirements from ROADMAP)
    • Step 2: Load all PLAN.md files in phase directory
    • Step 3: Parse must_haves from plan frontmatter
    • Step 4: Check requirement coverage
    • Step 5: Validate task structure
    • Step 6: Verify dependency graph
    • Step 7: Check key links planned
    • Step 8: Assess scope
    • Step 9: Verify must_haves derivation
    • Step 10: Determine overall status
  5. <issue_structure> (~60 lines) Output format for issues:

    issues:
      - plan: "16-01"
        dimension: "task_completeness"
        severity: "blocker"
        description: "Task 2 missing <verify> element"
        fix_hint: "Add verification command for build output"
    
  6. <structured_returns> (~50 lines) Return formats:

    • ## VERIFICATION PASSED — All checks pass
    • ## ISSUES FOUND — Structured list for planner Include plan_ids, issue_count, dimensions_failed
  7. <success_criteria> (~30 lines) Checklist for checker completion

Anti-patterns to document:

  • Checking code existence (that's gsd-verifier's job)
  • Running the application (this is static plan analysis)
  • Accepting vague tasks ("implement auth")
  • Missing dependency analysis

Key insight: Checker verifies plans WILL achieve goal, verifier verifies code DID achieve goal. Different timing, similar methodology. - File exists: ls agents/gsd-plan-checker.md - Line count: wc -l agents/gsd-plan-checker.md (400-600 lines) - Has all sections: grep -E "^<(role|core_principle|verification_dimensions|verification_process|issue_structure|structured_returns|success_criteria)>" agents/gsd-plan-checker.md | wc -l (7 sections) gsd-plan-checker.md created with complete plan verification expertise, follows gsd-verifier pattern, has all 7 required sections

Task 2: Add example verification scenarios agents/gsd-plan-checker.md Add `` section (~80 lines) after verification_process showing:

Example 1: Missing requirement coverage

Phase goal: "Users can authenticate"
Requirements: AUTH-01 (login), AUTH-02 (logout), AUTH-03 (session)

Plans found:
- 01-01: Login form and API
- 01-02: Session management

Issue: AUTH-02 (logout) has no covering task

Example 2: Broken dependency chain

Plan 02 frontmatter: depends_on: ["01", "03"]
Plan 03 frontmatter: depends_on: ["02"]

Issue: Circular dependency between 02 and 03

Example 3: Task missing verification

<task type="auto">
  <name>Create login endpoint</name>
  <files>src/app/api/auth/login/route.ts</files>
  <action>POST endpoint with bcrypt validation</action>
  <!-- Missing <verify> -->
  <done>Login works</done>
</task>

Issue: Task missing <verify> element - cannot confirm completion

Example 4: Scope exceeded

Plan 01 has 5 tasks with 12 files modified
Estimated context: ~80%

Issue: Plan exceeds 50% context target, split into 2-3 plans
grep -c "" agents/gsd-plan-checker.md (should be 1) Examples section added with 4 verification scenarios covering common issues - [ ] agents/gsd-plan-checker.md exists - [ ] File is 400-600 lines - [ ] All 7 main sections present - [ ] Examples section present with 4 scenarios - [ ] Follows gsd-verifier frontmatter pattern - [ ] Structured returns match BRIEF spec

<success_criteria>

  • gsd-plan-checker agent created
  • Agent has complete plan verification methodology
  • Six verification dimensions documented
  • Examples cover common failure modes
  • Output format consumable by orchestrator </success_criteria>
After completion, create `.planning/phases/16-plan-verification-loop/16-01-SUMMARY.md`