github / github/spec-kit

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

Abierto
#3,478 2 comentarios 5 reacciones 0 asignados Ver en GitHub
invalid stale
Lenguaje dominante
Python
Estrellas
137k
Forks
12.3k
Merge medio
2 d 12 h
PR fusionados (30 d)
159

Descripción

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

Guía de contribución

Abrir la guía de contribución

Línea de trabajo

Start with the existing command skeleton in templates/commands and the Specify CLI integration used by `specify integration install `. Review spec-driven.md and verify that templates/commands/explore.md provides the stance and repertoire, hands off only to specify, creates no artifacts, installs for all supported agents, and is documented as an optional pre-specify phase.

Escrito por el modelo de indexación a partir del texto del issue.

Evaluación

Stack tecnológico
markdown, python
Área
cli, documentation
Tipo de issue
Nueva funcionalidad
Dificultad
4/5
Tiempo estimado
3-5 días
Estado de actividad
Activo
Claridad
Bien especificado
Aptitud para principiantes
38/100

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.