Skip to content

[Feature]: Add /speckit.explore as a pre-specify thinking phase #3478

Description

@dev-v

Problem Statement

Spec Kit's SDD pipeline starts at specify — a user's idea is fed directly as $ARGUMENTS and immediately structured into spec.md. There is no phase for thinking through the problem before committing to a specification. This forces premature structuring: vague ideas get squeezed into spec templates, and the exploration that should happen before specification (questioning assumptions, comparing approaches, reading the codebase) either gets lost or leaks into the specify command's already-long template.

The result is lower-quality specs that miss hidden complexity, skip alternative approaches, and require more downstream rework.

Proposed Solution

Add a new core command speckit.explore — a pre-specify thinking phase that acts as a "thinking partner" stance rather than a procedure-driven workflow.

Key characteristics:

  • No file artifacts — explore produces no directories, no spec files, runs no scripts. Its output is a structured exploration summary handed off to specify via the existing handoff mechanism.
  • Stance + repertoire, not numbered steps — the template uses a two-layer structure: a stance (curious, open, visual, grounded, patient, assumption-challenging) and a repertoire of exploratory actions (problem-space exploration, codebase investigation, option comparison, visualization, risk surfacing) that the AI calls upon as context demands — not a 1→2→3→4→5 procedure.
  • Convergence detection — the AI detects when thinking has crystallized and proactively offers handoff to specify. The user can accept (→ specify) or reject (→ continue exploring).
  • Structured summary — on handoff, explore generates a four-part summary: framed problem, key findings, chosen direction, and rejected paths (prevents the spec from re-entertaining eliminated options).
  • Pipeline extension — the SDD pipeline becomes: explore → specify → clarify → plan → tasks → implement. Explore is an optional entry point; users can still invoke specify directly.

The change is purely additive: one new template file (templates/commands/explore.md), no changes to existing templates, no Python code changes, no new scripts.

Alternatives Considered

  1. Extension-based (extensions/explore/) — rejected because explore is a core SDD phase concept, not an opt-in extension. Making it an extension means users who don't install it miss a fundamental part of the pipeline.
  2. Preset-only — rejected because it would make explore unavailable to projects that don't use that preset, fragmenting the SDD pipeline.
  3. Expand specify's template — rejected because specify's template is already long; adding exploratory thinking to it would conflate two distinct phases (thinking vs. structuring).

Component

Specify CLI (initialization, commands)

AI Agent

All agents

Use Cases

  1. Vague idea to structured spec — A user has a rough feature idea ("we need better search") but hasn't thought through the problem framing. Explore helps them clarify what they are actually solving before committing to a spec.
  2. Codebase investigation before spec — A user wants to add a feature but needs to understand existing patterns, integration points, and hidden complexity before writing the spec. Explore grounds the discussion in the actual codebase.
  3. Comparing approaches — Multiple viable architectures surface during thinking. Explore helps build comparison tables and tradeoff matrices, then captures rejected paths so the spec does not re-entertain them.
  4. Challenging assumptions — A user assumes they need X, but the codebase already has Y. Explore surfaces this: "You said you need X, but the codebase already has Y — would that work?"

Acceptance Criteria

  • templates/commands/explore.md exists with the stance + repertoire structure
  • specify integration install <agent> installs explore alongside other core commands
  • Explore produces no file artifacts (no directories, no spec files)
  • Explore's handoff targets only specify (linear pipeline)
  • Documentation updated: spec-driven.md mentions explore as an optional pre-specify phase
  • Works with all supported agent integrations

Additional Context

I have a working implementation ready as a PR. The explore template adapts spec-kit's existing command skeleton (frontmatter, Pre-Execution Checks, Done When) while replacing the procedural Outline with a stance + repertoire structure.

The design was informed by a structured exploration process, which surfaced the key design tension: explore is a stance, not a workflow. Compressing it into numbered steps would destroy its value. The template resolves this by keeping the skeleton (for structural consistency with other commands) but replacing the procedural Outline with a non-sequential repertoire.

This is a large change (new template, 230 lines), so per the Contributing guidelines I am opening this issue for discussion before submitting a PR. Happy to adjust the design based on maintainer feedback.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions