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

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:

// 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:

# 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:

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:

# 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:

# 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 (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 (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 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.

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 and plan-phase.md specifically treat these phases as gap-closure steps, making them most effective when used within that context.

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