# How the gsd-build Plan-Phase Workflow Validates Plans Before Execution > Learn how the gsd-build plan-phase workflow validates plans through automated goal-backward verification and revision iterations, ensuring robust execution. - Repository: [GSD/get-shit-done](https://github.com/gsd-build/get-shit-done) - Tags: how-to-guide - Published: 2026-02-16 --- **The gsd-build plan-phase workflow validates plans by spawning the `gsd-plan-checker` agent to run goal-backward verification across seven quality dimensions, automatically triggering up to three revision iterations if blockers are detected.** The `gsd:plan-phase` command in the [gsd-build/get-shit-done](https://github.com/gsd-build/get-shit-done) repository orchestrates a rigorous validation pipeline that ensures only high-quality, executable plans reach the implementation stage. This plan-phase validation process prevents costly rework by verifying requirement coverage, dependency correctness, and task completeness before any code is generated. ## The Validation Pipeline Architecture The validation workflow is defined in [`get-shit-done/workflows/plan-phase.md`](https://github.com/gsd-build/get-shit-done/blob/main/get-shit-done/workflows/plan-phase.md) and orchestrated through [`commands/gsd/plan-phase.md`](https://github.com/gsd-build/get-shit-done/blob/main/commands/gsd/plan-phase.md). After the `gsd-planner` agent generates [`PLAN.md`](https://github.com/gsd-build/get-shit-done/blob/main/PLAN.md) files, the workflow immediately spawns the `gsd-plan-checker` agent to verify the output. The pipeline follows this sequence: 1. **Initialize context** – Load [`ROADMAP.md`](https://github.com/gsd-build/get-shit-done/blob/main/ROADMAP.md), [`STATE.md`](https://github.com/gsd-build/get-shit-done/blob/main/STATE.md), [`CONTEXT.md`](https://github.com/gsd-build/get-shit-done/blob/main/CONTEXT.md), and existing research. 2. **Generate plans** – The planner creates detailed `*-PLAN.md` files with structured front-matter. 3. **Validate plans** – The checker runs goal-backward verification against the phase goal. 4. **Revision loop** – If blockers exist, the planner receives feedback and updates the plans (max 3 iterations). 5. **Final status** – Upon "VERIFICATION PASSED", the workflow proceeds to execution. ## The Seven Dimensions of Plan Validation The `gsd-plan-checker` agent, defined in [`agents/gsd-plan-checker.md`](https://github.com/gsd-build/get-shit-done/blob/main/agents/gsd-plan-checker.md), validates plans across seven specific dimensions. Each dimension targets a common failure mode in software planning. ### Requirement Coverage The checker verifies that every requirement in the phase goal has at least one corresponding task in the plan. If a requirement lacks coverage, the checker flags it as a blocker. ### Task Completeness Each `` element must contain: - `` – Target files to modify - `` – Specific implementation step - `` – Verification command or criteria - `` – Completion condition Missing any required field triggers a blocker. ### Dependency Correctness The checker validates `depends_on` references in the plan front-matter: - References must exist and be acyclic - Wave numbers must be consistent with dependencies Circular dependencies or invalid references are flagged as blockers. ### Key-Links Planned Artifacts must be wired together correctly. For example, if a UI component is created, the plan must include the corresponding API call or data fetch. Missing connections generate warnings or blockers depending on severity. ### Scope Sanity Plans must adhere to size constraints: - 2-3 tasks per plan - 5-8 files modified per plan - Total context usage ≤ 50% Exceeding these limits triggers a blocker with a suggestion to split the plan. ### Verification Derivation The `must_haves` section in the plan front-matter must contain: - **Truths**: User-observable outcomes, not implementation details - **Artifacts**: Files that provide the truths - **Key links**: Connections between artifacts Implementation-focused truths (e.g., "bcrypt installed") are flagged as warnings. ### Context Compliance (Optional) If [`CONTEXT.md`](https://github.com/gsd-build/get-shit-done/blob/main/CONTEXT.md) contains locked decisions or deferred ideas, the checker verifies: - Locked decisions are honored in the plan - Deferred ideas are excluded from the current phase Violations are flagged as blockers. ## The Revision Loop: Iterative Plan Correction When the `gsd-plan-checker` detects blockers, the workflow enters a revision loop defined in [`get-shit-done/workflows/plan-phase.md`](https://github.com/gsd-build/get-shit-done/blob/main/get-shit-done/workflows/plan-phase.md) (steps 12-13). The process works as follows: 1. **Issue collection** – The checker outputs a structured YAML list of issues with severity, description, and fix hints. 2. **Planner invocation** – The orchestrator sends the existing plans and the issue list back to the `gsd-planner` agent. 3. **Targeted updates** – The planner makes surgical updates to address the specific issues without rewriting the entire plan. 4. **Re-validation** – The updated plans are sent back to the checker. This loop executes a maximum of **three iterations**. After three attempts, if blockers persist, the user can: - Force proceed despite issues - Provide additional guidance to the planner - Abort the workflow ## Running Plan-Phase Validation You can trigger the validation workflow using the `gsd:plan-phase` command with various flags to control the validation behavior. ### Basic Validation Run ```bash # Plan phase 3 with full validation gsd:plan-phase 3 ``` ### Skipping Validation ```bash # Generate plans but skip the checker (not recommended for production) gsd:plan-phase 3 --skip-verify ``` ### Gap-Closure Mode ```bash # Validate against existing verification gaps without running research gsd:plan-phase 3 --gaps ``` ### Understanding Checker Output When validation fails, the checker produces structured YAML output that feeds into the revision loop: ```yaml issues: - plan: "03-01" dimension: "task_completeness" severity: "blocker" description: "Task 1 missing element" fix_hint: "Add a curl command that confirms 200 response" - plan: "03-01" dimension: "scope_sanity" severity: "blocker" description: "Plan contains 5 tasks, exceeds limit of 3" fix_hint: "Split into two plans: auth-setup and auth-verification" ``` ## Summary The gsd-build plan-phase workflow validates plans through a rigorous multi-step process before execution: - **Goal-backward verification** performed by the `gsd-plan-checker` agent across seven quality dimensions including requirement coverage, dependency correctness, and scope sanity. - **Structured issue reporting** using YAML format with severity levels (blocker vs warning) and specific fix hints. - **Automated revision loop** allowing up to three iterative corrections between the planner and checker before human intervention. - **Front-matter validation** ensuring `must_haves` contain user-observable truths, proper artifact mappings, and valid dependency references. This validation architecture ensures that only complete, consistent, and scope-appropriate plans proceed to the execution phase, preventing costly implementation errors. ## Frequently Asked Questions ### What happens if the plan-checker finds blockers during validation? If the `gsd-plan-checker` identifies blocker-level issues, the workflow enters a revision loop. The orchestrator sends the existing plans and the structured issue list back to the `gsd-planner` agent, which makes targeted updates to address the specific problems. This loop runs up to three times; if blockers persist after three iterations, the user must choose to force proceed, provide additional guidance, or abort the workflow. ### How does the plan-phase workflow ensure requirements are actually covered by tasks? The `gsd-plan-checker` performs a **requirement coverage** verification as one of its seven dimensions. It maps every requirement listed in the phase goal against the tasks in the generated [`PLAN.md`](https://github.com/gsd-build/get-shit-done/blob/main/PLAN.md) files. If any requirement lacks a corresponding task that fulfills it, the checker flags this as a blocker with a specific description indicating which requirement is uncovered and a hint suggesting what type of task should be added. ### Can I skip the validation step if I'm in a hurry? Yes, but it is not recommended for production workflows. You can bypass the `gsd-plan-checker` by running `gsd:plan-phase --skip-verify`. This flag tells the orchestrator to generate the [`PLAN.md`](https://github.com/gsd-build/get-shit-done/blob/main/PLAN.md) files using the `gsd-planner` agent but skip the validation step entirely. However, doing so risks proceeding with incomplete tasks, broken dependencies, or scope violations that the checker would normally catch and correct through the revision loop. ### What specific fields must a PLAN.md file contain to pass validation? To pass the `gsd-plan-checker` validation, a [`PLAN.md`](https://github.com/gsd-build/get-shit-done/blob/main/PLAN.md) file must include specific front-matter fields and task elements. The YAML front-matter must contain `phase`, `plan`, `type`, `wave`, `depends_on`, `files_modified`, `autonomous`, and `must_haves` (with nested `truths`, `artifacts`, and `key_links`). Within the document, each `` must include ``, ``, ``, and `` elements. Missing any of these required fields triggers a task_completeness blocker during validation.