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

> Discover how the gsd-build gap closure cycle automates remediation for incomplete features during phase verification, ensuring continuous progress until completion.

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

---

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

```bash

# Step 1: Run verification to detect gaps

gsd:verify-phase 03

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

# Status: gaps_found

```

```bash

# 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: [...]

```

```bash

# 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

```

```bash

# Step 4: Automatic re-verification occurs after execution

# No manual command needed; orchestrator runs verify_phase_goal

# If gaps persist, cycle repeats automatically

```

```bash

# 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`](https://github.com/gsd-build/get-shit-done/blob/main/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`](https://github.com/gsd-build/get-shit-done/blob/main/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`](https://github.com/gsd-build/get-shit-done/blob/main/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`](https://github.com/gsd-build/get-shit-done/blob/main/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`](https://github.com/gsd-build/get-shit-done/blob/main/workflows/execute-phase.md) explicitly describes this loop, checking verification status after each execution and triggering subsequent planning cycles if gaps persist.