github / github/spec-kit

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

未关闭
#3,478 2 条评论 5 个 reaction 已指派 0 人 在 GitHub 查看
invalid stale
主要语言
Python
星标
137k
派生
12.3k
平均合并
2 天 12 小时
30 天内合并 PR
159

描述

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

贡献指南

打开贡献指南

调研方向

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.

由索引模型根据 Issue 内容生成。

评估

技术栈
markdown, python
领域
cli, documentation
Issue 类型
功能
难度
4/5
预计耗时
3-5 天
活跃度
活跃
描述清晰度
描述清楚
新手友好度
38/100

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。