How the Gap Closure Cycle in gsd-build Handles Incomplete Features During Phase Verification

The gap closure cycle in gsd-build automatically generates targeted remediation plans when phase verification detects missing must-haves, executing and re-verifying in a continuous loop until the phase passes or requires human intervention.

The gsd-build repository implements a rigorous goal-backward verification system that ensures every phase achieves its declared objectives. When the gsd-verifier sub-agent discovers gaps between expected outcomes and actual artifacts, the gap closure cycle initiates an automated remediation loop that bridges the distance between task completion and goal achievement.

What Triggers the Gap Closure Cycle

The cycle begins in workflows/verify-phase.md when the verify_phase_goal step examines the phase's must-haves against actual truths, artifacts, and wiring. If the verification produces a *-VERIFICATION.md file with status gaps_found, the orchestrator immediately flags the phase for gap closure and prevents normal completion.

The Six-Step Gap Closure Process

Step 1: Verification Detects Gaps

The gsd-verifier sub-agent runs after phase execution in workflows/execute-phase.md (lines 90-103). It produces a *-VERIFICATION.md file marking status as gaps_found and listing missing must-haves that block phase completion.

Step 2: Gap-Closure Plans Are Generated

The orchestrator calls workflows/plan-phase.md with the --gaps flag. The planner reads the verification report and creates *-PLAN.md files with front-matter containing gap_closure: true, focusing solely on the missing items rather than re-executing the entire phase.

Step 3: Execute Only the Gap-Closure Plans

Running gsd:execute-phase <phase> --gaps-only triggers the discover_and_group_plans step in workflows/execute-phase.md (line 59). This filters the plan inventory to keep only those with gap_closure: true and executes them in the standard wave-based execution engine.

Step 4: Re-Run Verification

After gap-only execution finishes, the orchestrator automatically invokes verify_phase_goal again in workflows/execute-phase.md (lines 79-84). The verifier re-examines the same must-haves now that missing artifacts have been added or wired.

Step 5: Loop or Finish

If verification still reports gaps, the cycle repeats: new gap-closure plans are created, executed, and re-verified. When all must-haves verify successfully, status becomes passed and normal phase-completion flow continues with roadmap updates and next-phase auto-advance.

Step 6: Parent-Phase Cleanup for Decimal Phases

When the completed phase is a gap-closure sub-phase (e.g., 4.1), the close_parent_artifacts step in workflows/execute-phase.md (lines 30-76) updates the parent UAT and related debug sessions, marking their status as resolved and committing changes via gsd-tools.cjs.

Key Workflow Files Powering the Gap Closure Cycle

• workflows/verify-phase.md: Implements goal-backward verification and produces the decisive *-VERIFICATION.md files consumed by the gap-closure logic.
• workflows/execute-phase.md: Orchestrates plan execution, handles --gaps-only filtering via discover_and_group_plans, manages re-verification through verify_phase_goal, and performs parent-phase cleanup via close_parent_artifacts.
• workflows/plan-phase.md: Generates gap-closure plans when invoked with --gaps, reading verification reports and emitting plans with gap_closure: true front-matter.
• templates/verification-report.md: Template structure for verification reports that drive the gap-closure loop.
• bin/gsd-tools.cjs: CLI helper used by workflows to read state, roadmap data, and commit files during cleanup operations.

Practical Commands for Running the Gap Closure Cycle

# Step 1: Run verification to detect gaps

gsd:verify-phase 03

# Produces .planning/phases/03-xyz/03-VERIFICATION.md

# Status: gaps_found

# Step 2: Generate gap-closure plans

gsd:plan-phase 03 --gaps

# Creates files like 03-04-gap-closure-PLAN.md with frontmatter:

#   gap_closure: true

#   must_haves: [...]

# Step 3: Execute only gap-closure plans

gsd:execute-phase 03 --gaps-only

# discover_and_group_plans filters for gap_closure: true

# Runs targeted plans in wave-based execution engine

# Step 4: Automatic re-verification occurs after execution

# No manual command needed; orchestrator runs verify_phase_goal

# If gaps persist, cycle repeats automatically

# Step 5: Parent-phase cleanup for decimal phases (e.g., 4.1)

# Automatically handled by close_parent_artifacts step

# Commits via: node ~/.claude/get-shit-done/bin/gsd-tools.cjs commit \

#   "docs(phase-4): resolve UAT gaps after 4.1 gap closure" \

#   --files .planning/phases/*4*/*-UAT.md

Summary

• The gap closure cycle automatically triggers when gsd-verifier detects missing must-haves in a phase verification report.
• The cycle generates targeted gap-closure plans with gap_closure: true front-matter, executes them via --gaps-only filtering, and re-verifies results in a continuous loop.
• Key orchestration happens in workflows/execute-phase.md through the discover_and_group_plans, verify_phase_goal, and close_parent_artifacts steps.
• Decimal sub-phases (e.g., 4.1) automatically trigger parent-phase cleanup to resolve UAT and debug sessions.
• The cycle continues until verification passes or requires human intervention, ensuring rigorous goal-backward compliance before phase completion.

Frequently Asked Questions

What triggers the gap closure cycle in gsd-build?

The cycle triggers when the verify_phase_goal step in workflows/execute-phase.md produces a verification report with status gaps_found. This occurs when the gsd-verifier sub-agent detects that required truths, artifacts, or wiring specified in the phase's must-haves are missing after initial execution.

How does gsd-build filter plans during gap closure execution?

The discover_and_group_plans step in workflows/execute-phase.md filters the plan inventory when the --gaps-only flag is passed to gsd:execute-phase. It retains only plans whose front-matter contains gap_closure: true, ensuring the wave-based execution engine runs only targeted remediation plans rather than the full phase plan set.

What happens to parent phases when a decimal sub-phase completes gap closure?

When a gap-closure sub-phase with a decimal identifier (e.g., 4.1) completes successfully, the close_parent_artifacts step in workflows/execute-phase.md automatically updates the parent phase's UAT files and related debug sessions. It marks their status as resolved and commits these changes via gsd-tools.cjs, ensuring the parent phase reflects the resolved gaps.

Can the gap closure cycle run indefinitely?

Yes, the cycle will continue generating new gap-closure plans, executing them, and re-verifying results until either the phase achieves passed status or human intervention is required. The verify_phase_goal step in workflows/execute-phase.md explicitly describes this loop, checking verification status after each execution and triggering subsequent planning cycles if gaps persist.

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