How gsd-build's Gap Closure Workflow Resolves Verification Failures

The gap closure workflow automatically diagnoses verification failures, generates validated fix plans, and iteratively executes them until all gaps are closed.

The gsd-build/get-shit-done repository implements a self-healing build system where verification failures trigger an automated gap closure workflow. This process transforms missing must-haves and broken behaviors into actionable, validated fix plans without manual intervention.

How the Gap Closure Workflow Detects Verification Failures

When a phase completes execution, the verifier sub-agent (gsd-verifier) produces a *-VERIFICATION.md file containing one of three statuses:

• passed — All automated checks succeeded
• human_needed — Automated checks passed but requires human validation
• gaps_found — One or more must-haves were not satisfied, triggering the gap closure workflow

According to the source code in get-shit-done/workflows/execute-phase.md【L98-L103】, when the verifier returns gaps_found, it prints a summary and suggests running /gsd:plan-phase {phase} --gaps【L15-L30】.

The Six-Step Gap Resolution Process

The gap closure workflow orchestrates a six-step loop managed primarily through get-shit-done/workflows/verify-work.md and get-shit-done/workflows/execute-phase.md.

1. Diagnose Failures with Root-Cause Analysis

Upon detecting gaps, verify-work.md spawns parallel debug agents to investigate each issue without user interaction【L25-L34】. These agents read the UAT.md file, add a debug_session: block, and update the file with root-cause notes【L25-L41】.

2. Generate Gap-Closure Plans

After diagnosis, verify-work.md spawns the planner in gap-closure mode【L58-L65】. The planner receives:

• Phase context (phase_number, phase_dir)
• Updated UAT.md with diagnoses
• Project state (STATE.md, ROADMAP.md)

It creates *-PLAN.md files that must contain gap_closure: true so execution knows they belong to the closure cycle【agents/gsd-planner.md#L11-L14】.

3. Validate Plans with the Plan-Checker

verify-work.md immediately runs the plan-checker sub-agent on the generated plans【L90-L104】. The checker returns either:

• ## VERIFICATION PASSED — Plans satisfy all constraints

• ## ISSUES FOUND — Structured list of remaining problems

4. Iterate Up to Three Times

If the checker reports issues, verify-work.md enters a revision loop【L41-L89】:

1. Increment iteration_count
2. Feed checker issues back to the planner (revision mode)
3. Re-run the checker

The loop stops after three iterations. If problems persist, the user chooses to force execution, provide manual guidance, or abandon the cycle.

5. Execute Approved Fixes

When the planner-checker cycle succeeds, the system runs:

/gsd:execute-phase {phase_number} --gaps-only

The execute-phase workflow only runs plans marked with gap_closure: true【commands/gsd/execute-phase.md#L33-L35】, updates debug sessions, and commits results【get-shit-done/workflows/execute-phase.md#L61-L76】.

6. Re-Verify and Close the Loop

After executing fixes, execute-phase.md calls the verifier again via verify_phase_goal. The verifier returns:

• passed — Gaps closed, roadmap advances
• gaps_found — New failures trigger another gap-closure cycle

This cycle is documented in the "Gap closure cycle" comment in execute-phase.md【L36-L38】.

Key Workflow Files and Their Roles

File	Role in Gap Closure Workflow
get-shit-done/workflows/verify-work.md	Orchestrates verification, diagnosis, and the planner-checker loop【L46-L60】
get-shit-done/workflows/execute-phase.md	Runs phase tasks, re-verifies, and launches gap-closure cycles【L36-L38】
agents/gsd-planner.md	Generates gap-closure plans with gap_closure: true flag【L11-L14】
agents/gsd-plan-checker.md	Validates plans before execution
agents/gsd-verifier.md	Produces verification reports with gaps_found status
commands/gsd/execute-phase.md	CLI entry point for --gaps-only execution mode【L33-L35】

Practical Usage Examples

Run verification after a phase completes:

/gsd:verify-work 04

If gaps are found, the gap closure workflow automatically diagnoses and plans. To execute the generated fixes:

/gsd:execute-phase 04 --gaps-only

Then re-verify to confirm closure:

/gsd:verify-work 04

For manual control, invoke the planner directly in gap mode:

/gsd:plan-phase 04 --gaps
/gsd:execute-phase 04 --gaps-only

Summary

• The gap closure workflow triggers automatically when verification returns gaps_found status.
• Root-cause analysis runs via parallel debug agents that update UAT.md with diagnostic blocks.
• Fix plans are generated with the mandatory gap_closure: true flag and validated by a plan-checker sub-agent.
• The system iterates up to three times between planner and checker before requiring human intervention.
• Execution uses the --gaps-only flag to run only gap-closure plans, followed by re-verification to confirm the cycle is complete.

Frequently Asked Questions

What triggers the gap closure workflow?

The gap closure workflow activates when the verifier sub-agent (gsd-verifier) returns a gaps_found status in the *-VERIFICATION.md file. This occurs when automated checks detect missing must-haves or broken behaviors that prevent the phase from passing validation.

How many times will the workflow retry failed plans?

The planner-checker revision loop executes a maximum of three iterations. If the plan-checker sub-agent continues reporting issues after three attempts, the system prompts the user to force execution, provide manual guidance, or abandon the automatic cycle.

Can I manually trigger gap closure planning?

Yes. While the workflow runs automatically upon detecting gaps, you can manually invoke the planner in gap-closure mode using /gsd:plan-phase {phase_number} --gaps. This creates *-PLAN.md files flagged with gap_closure: true that the execution engine recognizes.

What happens if gap closure fails after maximum iterations?

If the gap closure workflow cannot produce passing plans after three revision cycles, the system presents three options: force execution of the current plans despite known issues, accept manual guidance to revise the plans further, or abandon the automatic cycle and switch to fully manual planning and execution.

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