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

> Discover how gsd-builds gap closure workflow automatically diagnoses and resolves verification failures by generating and executing validated fix plans. Close gaps efficiently with gsd-build.

- Repository: [GSD/get-shit-done](https://github.com/gsd-build/get-shit-done)
- Tags: how-to-guide
- Published: 2026-02-16

---

**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`](https://github.com/gsd-build/get-shit-done/blob/main/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`](https://github.com/gsd-build/get-shit-done/blob/main/get-shit-done/workflows/verify-work.md) and [`get-shit-done/workflows/execute-phase.md`](https://github.com/gsd-build/get-shit-done/blob/main/get-shit-done/workflows/execute-phase.md).

### 1. Diagnose Failures with Root-Cause Analysis

Upon detecting gaps, [`verify-work.md`](https://github.com/gsd-build/get-shit-done/blob/main/verify-work.md) spawns parallel debug agents to investigate each issue without user interaction【L25-L34】. These agents read the [`UAT.md`](https://github.com/gsd-build/get-shit-done/blob/main/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`](https://github.com/gsd-build/get-shit-done/blob/main/verify-work.md) spawns the **planner** in gap-closure mode【L58-L65】. The planner receives:

- Phase context (`phase_number`, `phase_dir`)
- Updated [`UAT.md`](https://github.com/gsd-build/get-shit-done/blob/main/UAT.md) with diagnoses
- Project state ([`STATE.md`](https://github.com/gsd-build/get-shit-done/blob/main/STATE.md), [`ROADMAP.md`](https://github.com/gsd-build/get-shit-done/blob/main/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`](https://github.com/gsd-build/get-shit-done/blob/main/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`](https://github.com/gsd-build/get-shit-done/blob/main/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:

```bash
/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`](https://github.com/gsd-build/get-shit-done/blob/main/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`](https://github.com/gsd-build/get-shit-done/blob/main/execute-phase.md)【L36-L38】.

## Key Workflow Files and Their Roles

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

## Practical Usage Examples

Run verification after a phase completes:

```bash
/gsd:verify-work 04

```

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

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

```

Then re-verify to confirm closure:

```bash
/gsd:verify-work 04

```

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

```bash
/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`](https://github.com/gsd-build/get-shit-done/blob/main/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.