How the discuss-phase in gsd-build Captures Implementation Decisions

The discuss-phase in gsd-build extracts and persists implementation decisions by identifying ambiguous requirements, forcing explicit user selection, conducting focused clarification loops, and writing the results to a structured CONTEXT.md file that downstream agents must follow.

The discuss-phase is the mandatory first step in every phase of the gsd-build workflow from the gsd-build/get-shit-done repository. Its primary function is to transform implicit design conversations into explicit, version-controlled decisions that prevent drift during planning and execution.

What Is the discuss-phase?

The discuss-phase is a workflow step defined in get-shit-done/workflows/discuss-phase.md that runs before any planning or coding occurs. It acts as a decision gate that forces the user to resolve ambiguities in the current phase description. According to the source code, the phase scans the requirements and presents a multi-select list of "gray areas" that require explicit design choices.

The Four-Step Decision Capture Process

The discuss-phase follows a rigid protocol to ensure no implicit assumptions leak into the build process.

Identify Gray Areas

The workflow first analyzes the phase description to find ambiguous or design-heavy topics. In discuss-phase.md (lines 170-178), the system scans for requirements that lack concrete implementation details and compiles them into a selectable list. These gray areas represent the decision points that could cause inconsistency if left unresolved.

Select Topics for Discussion

The user must explicitly choose which items to discuss. The source code at discuss-phase.md (lines 208-213) enforces that skipping is not allowed; the user must pick one or more items from the gray area list. This mandatory selection ensures that every decision point is addressed before the workflow proceeds.

Focused Discussion Loops

For each selected area, the assistant enters a clarification loop. According to discuss-phase.md (lines 244-250), the system asks targeted questions, gathers preferences, examples, and constraints. The loop continues iteratively until the user explicitly signals satisfaction, ensuring that the captured decisions reflect the user's actual intent.

Generate CONTEXT.md

After discussion completes, the workflow writes a phase-specific CONTEXT.md file. The generation logic in discuss-phase.md (lines 309-342) structures the file into three top-level sections:

• Decisions – Concrete implementation choices captured from the discussion.
• Discretion Areas – Spots where the executor may exercise judgment.
• Deferred Ideas – Concepts that belong to later phases.

The template driving this structure lives in templates/context.md (lines 7-40), which defines the headings and placeholder text that the discuss-phase populates with the captured decisions.

How Downstream Agents Consume Captured Decisions

The CONTEXT.md file acts as a contract that downstream agents must follow. According to the source code, the planner, plan-checker, and phase-researcher all read the phase-specific *-CONTEXT.md to ensure alignment:

• Planner: Reads <user_decisions> tags produced by the discuss-phase to generate plans that respect the locked decisions (agents/gsd-planner.md, line 31).
• Plan-Checker: Validates that generated plans honor the captured decisions (agents/gsd-plan-checker.md, line 27).
• Phase-Researcher: Pulls decisions to guide research priorities (agents/gsd-phase-researcher.md, line 22).

This consumption pattern ensures that once the discuss-phase locks in a decision, the entire pipeline maintains consistency with that choice.

CLI Usage and Workflow Integration

The discuss-phase is exposed to users through the /gsd:discuss-phase <N> command, where <N> represents the phase number to discuss. According to the user documentation in docs/USER-GUIDE.md (lines 146-152) and README.md (lines 146-152), this command must be run before any planning occurs for the specified phase. The documentation describes the command as the mechanism that "captures implementation decisions" and locks in user preferences, preventing drift during the build process.

Summary

• The discuss-phase is a mandatory gate in gsd-build that runs before planning to extract explicit implementation decisions.
• It follows a four-step protocol: identify gray areas, force user selection, conduct clarification loops, and write structured output.
• Decisions are persisted to a phase-specific CONTEXT.md file with three sections: Decisions, Discretion Areas, and Deferred Ideas.
• Downstream agents including the planner, plan-checker, and phase-researcher consume CONTEXT.md to ensure plan alignment.
• Users trigger the workflow via the /gsd:discuss-phase <N> CLI command documented in USER-GUIDE.md and README.md.

Frequently Asked Questions

What happens if I skip the discuss-phase in gsd-build?

Skipping is architecturally prevented. The workflow in discuss-phase.md (lines 208-213) enforces that users must explicitly select one or more gray areas for discussion before proceeding. This mandatory selection ensures that no phase begins without locked implementation decisions.

How does the discuss-phase differ from the planning phase?

The discuss-phase captures what to build and how to implement it, while the planning phase determines the steps to execute that implementation. According to agents/gsd-planner.md (line 31), the planner reads the decisions captured by discuss-phase to ensure the execution plan respects the locked-in design choices.

What file format does the discuss-phase generate?

The discuss-phase generates a Markdown file named CONTEXT.md (or phase-specific variants like phase-2-CONTEXT.md). The template in templates/context.md (lines 7-40) structures this file with three top-level sections: Decisions, Discretion Areas, and Deferred Ideas.

Can I modify decisions after the discuss-phase completes?

While the system generates CONTEXT.md as a persistent artifact, the workflow is designed to treat these decisions as locked contracts for the current phase. Downstream agents like the plan-checker (agents/gsd-plan-checker.md, line 27) validate plans against these decisions. To change decisions, you would typically re-run /gsd:discuss-phase <N> for that specific phase.

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