# Decimal Phase Pattern for Gap Closure in gsd-build: A Complete Technical Guide

> Discover the decimal phase pattern for gap closure in gsd-build. Learn how <base-phase>.<n> enables targeted workflow execution and improves development efficiency.

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

---

**In gsd-build, gap-closure phases use a decimal pattern of `<base-phase>.<n>` where the base is a two-digit integer and n is a sequential counter, allowing targeted workflow execution without disrupting the main roadmap.**

The decimal phase pattern is a core naming convention in the gsd-build system that enables precise insertion of remediation work between established roadmap phases. When the build system detects missing artifacts or unwired components—gaps in the workflow—it generates decimal-indexed phases that slot between integer phases to execute focused closure plans.

## Understanding the Decimal Phase Pattern Structure

The pattern follows a strict format: `<base-phase>.<n>`.

- **Base phase**: A two-digit integer representing the parent phase (e.g., `06` rather than `6`)
- **Decimal suffix**: A sequential integer starting at `1` that increments for each gap discovered within that base phase

This normalization ensures consistent directory sorting and clear hierarchical relationships. For example, phase `6` becomes `06.1` for its first gap-closure child, while phase `12` would generate `12.1`, `12.2`, and so on.

## How Gap Closure Uses Decimal Phases

When gsd-build discovers a gap—such as a missing dependency or incomplete component—it triggers the gap-closure mechanism:

1. **Identify the containing phase**: The system locates the integer phase where the gap exists
2. **Normalize the base**: The phase number is padded to two digits (`06`)
3. **Generate the decimal**: The next sequential decimal is appended (`06.1`)
4. **Create the workspace**: A new directory is established at `.planning/phases/06.1-<slug>`

This insertion method allows developers to execute remediation workflows without reordering or renumbering the existing roadmap phases.

## Implementation in gsd-tools.cjs

The decimal phase logic is implemented in the CLI tool `gsd-tools.cjs` within the `get-shit-done` repository.

### The cmdPhaseNextDecimal Function

The core algorithm resides in the `cmdPhaseNextDecimal` function at lines 996-1063 of `gsd-tools.cjs`:

```javascript
// src: gsd-tools.cjs → cmdPhaseNextDecimal
function cmdPhaseNextDecimal(cwd, basePhase, raw) {
  const phasesDir = path.join(cwd, '.planning', 'phases');
  const normalized = normalizePhaseName(basePhase);   // pads to two digits
  …
  // Find existing decimal phases like “06.1”, “06.2”, …
  const decimalPattern = new RegExp(`^${normalized}\\.(\\d+)`);
  const existingDecimals = [];

  for (const dir of dirs) {
    const match = dir.match(decimalPattern);
    if (match) existingDecimals.push(`${normalized}.${match[1]}`);
  }

  // Determine next decimal
  let nextDecimal;
  if (existingDecimals.length === 0) {
    nextDecimal = `${normalized}.1`;
  } else {
    const lastNum = parseInt(existingDecimals[existingDecimals.length - 1].split('.')[1], 10);
    nextDecimal = `${normalized}.${lastNum + 1}`;
  }

  output({ found: baseExists, base_phase: normalized, next: nextDecimal, existing: existingDecimals }, raw, nextDecimal);
}

```

The function uses a regular expression to identify existing decimal phases, parses the highest suffix number, and increments it to generate the next available slot.

## Practical Usage Examples

### Computing the Next Decimal Phase

To calculate the next gap-closure phase for base phase `6`:

```bash

# Compute the next decimal after phase 6

node ~/.claude/get-shit-done/bin/gsd-tools.cjs phase next-decimal 6

# → {"found":true,"base_phase":"06","next":"06.1","existing":[]}

```

For scripting purposes, use the `--raw` flag to extract just the phase string:

```bash
DECIMAL_PHASE=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs phase next-decimal 6 --raw)
echo "$DECIMAL_PHASE"   # prints 06.1

```

### Creating a Gap-Closure Directory

Once you have the decimal phase, create the workspace directory:

```bash

# Suppose we need to close a gap after phase 06

DECIMAL=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs phase next-decimal 06 --raw)   # => 06.1

SLUG=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs generate-slug "Fix auth bug" --raw)

PHASE_DIR=".planning/phases/${DECIMAL}-${SLUG}"
mkdir -p "$PHASE_DIR"
echo "Created $PHASE_DIR"

# Result: .planning/phases/06.1-fix-auth-bug/

```

### Executing Gap-Closure Workflows

To run only the gap-closure phases:

```bash

# After the plan for the decimal phase is generated:

gsd:execute-phase 06.1 --gaps-only

```

## Workflow Integration

The decimal phase pattern integrates with gsd-build's execution and planning workflows.

According to [`workflows/execute-phase.md`](https://github.com/gsd-build/get-shit-done/blob/main/workflows/execute-phase.md) (line 232), the `--gaps-only` flag instructs the system to skip non-decimal phases and treat only decimal-suffixed phases (e.g., `4.1`, `03.1`) as gap-closure steps.

The `plan-phase` workflow, documented in [`workflows/plan-phase.md`](https://github.com/gsd-build/get-shit-done/blob/main/workflows/plan-phase.md) (lines 184-199), creates plans with `mode: gap_closure` when the `--gaps` flag is supplied, generating phase numbers that follow the decimal pattern.

For detailed calculation logic, see [`references/decimal-phase-calculation.md`](https://github.com/gsd-build/get-shit-done/blob/main/references/decimal-phase-calculation.md) in the repository.

## Summary

- **Pattern format**: Decimal phases use `<base-phase>.<n>` where the base is a two-digit integer and n is a sequential counter starting at 1.
- **Gap closure**: The pattern allows insertion of remediation phases between integer roadmap phases without reordering existing work.
- **Implementation**: The `cmdPhaseNextDecimal` function in `gsd-tools.cjs` (lines 996-1063) handles normalization, existing phase detection, and increment logic.
- **Usage**: Compute decimal phases via CLI with `phase next-decimal`, create directories with the resulting slug, and execute with `--gaps-only` flags.

## Frequently Asked Questions

### What is the decimal phase pattern in gsd-build?

The decimal phase pattern is a naming convention that creates sub-phases between integer-indexed roadmap phases using the format `<base-phase>.<n>`. The base phase is normalized to two digits (e.g., `06`), and the decimal suffix starts at `1` and increments for each additional gap discovered within that base phase.

### How does gsd-build determine the next decimal phase number?

The system scans the `.planning/phases` directory for existing decimal phases matching the base pattern using the regex `^${normalized}\\.(\\d+)`. If no decimal phases exist, it assigns `.1`. Otherwise, it parses the highest existing decimal number, increments it by one, and returns the new phase identifier.

### Where is the decimal phase logic implemented in the codebase?

The core algorithm resides in the `cmdPhaseNextDecimal` function within `get-shit-done/bin/gsd-tools.cjs` at lines 996-1063. This function handles phase normalization, directory scanning, and decimal incrementation. Supporting documentation exists in [`get-shit-done/references/decimal-phase-calculation.md`](https://github.com/gsd-build/get-shit-done/blob/main/get-shit-done/references/decimal-phase-calculation.md).

### Can decimal phases be used outside of gap closure scenarios?

While decimal phases are primarily designed for gap closure—triggered by the `--gaps` and `--gaps-only` flags in the planning and execution workflows—the underlying CLI tools allow creation of decimal phases for any purpose. However, the workflow definitions in [`execute-phase.md`](https://github.com/gsd-build/get-shit-done/blob/main/execute-phase.md) and [`plan-phase.md`](https://github.com/gsd-build/get-shit-done/blob/main/plan-phase.md) specifically treat these phases as gap-closure steps, making them most effective when used within that context.