groundwork-discovery

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

groundwork-discovery

Elicits complete Gherkin scenarios through structured conversation — before any code is written. The

.feature

files produced here are the source of truth for both Superpowers (implementation) and groundwork-verify (validation).

在编写任何代码之前，通过结构化对话生成完整的Gherkin场景。此处生成的

.feature

文件是Superpowers（实现环节）和groundwork-verify（验证环节）的唯一可信来源。

Where this fits in the Superpowers flow

在Superpowers流程中的定位

groundwork-discovery (WHAT should it do?) → brainstorming (HOW should we build it?) → writing-plans → implementation → groundwork-verify

This skill captures observable behaviour as Gherkin scenarios. It does NOT decide architecture, tech choices, or implementation approach — that's brainstorming's job. After discovery writes the

.feature

file, suggest the user continues with the brainstorming skill.

groundwork-discovery（它应该实现什么？）→ brainstorming（我们应该如何构建它？）→ 编写计划 → 开发实现 → groundwork-verify

该功能将可观察行为记录为Gherkin场景。它不负责决定架构、技术选型或实现方案——这些是头脑风暴环节的工作。在生成

.feature

文件后，建议用户继续使用brainstorming功能。

When to use

使用时机

User wants to specify WHAT a feature should do — before deciding HOW to build it
User says "I need to build X" — start here to capture behaviour, then hand off to brainstorming
A bug or edge case was found and needs formal capture as a scenario
User says "let's spec this out", "what should this feature do?", "what are the edge cases?"

用户想要明确功能应实现的内容——在决定如何构建之前
用户说出“我需要开发X”——先使用此功能记录行为，再切换到头脑风暴环节
发现了bug或边缘情况，需要将其正式记录为场景
用户说出“我们来把需求明确下来”、“这个功能应该做什么？”、“有哪些边缘情况？”

When NOT to use

不适用时机

User already knows WHAT and wants to decide HOW (architecture, tech choices) → use brainstorming directly
User already has
```
.feature
```
files and wants to generate tests → use groundwork-verify
User wants to run or debug existing tests
The task is pure implementation with no specification gap

用户已经明确了要实现的内容，想要决定如何构建（架构、技术选型）→ 直接使用头脑风暴功能
用户已有
```
.feature
```
文件，想要生成测试用例 → 使用groundwork-verify
用户想要运行或调试现有测试
任务是纯开发实现，没有需求定义的缺口

Quick reference

快速参考

Command	Purpose	Output
`/groundwork new <feature>`	Full discovery interview from scratch	`docs/specs/features/<domain>/<feature>.feature`
`/groundwork extend <feature>`	Append scenarios to existing feature	Same file, new scenarios appended
`/groundwork review [feature]`	Format features as Superpowers context	Formatted context block

命令	用途	输出
`/groundwork new <feature>`	从零开始进行完整的需求调研	`docs/specs/features/<domain>/<feature>.feature`
`/groundwork extend <feature>`	为现有功能追加场景	同一文件，追加新场景
`/groundwork review [feature]`	将功能格式化为Superpowers可用的上下文	格式化后的上下文块

First action

第一步操作

Read

docs/specs/CONVENTIONS.md

if it exists. If not, use the defaults in this skill and offer to create it at the end.

如果

docs/specs/CONVENTIONS.md

文件存在，请先阅读。如果不存在，使用本功能中的默认规则，并在最后主动提出创建该文件。

Commands

命令说明

/groundwork new <feature-name>

/groundwork new <feature-name>

Discovery from scratch for a new feature.

Flow:

Ask for a high-level description of the feature in one or two sentences
Enter interview mode — one question at a time, in this order:

Phase	Question focus
Happy path	Walk me through the ideal use of this feature step by step
Actors	Who can use this feature? Are there different roles with different permissions?
Input validation	What input does this feature receive? What can be malformed, empty, or out of range?
System errors	What can go wrong outside the user's control? (network, database, third-party services)
Idempotency	What happens if the operation is repeated? Is it safe to call twice?
Concurrency	What if two users trigger this simultaneously?
Rollback	Can this operation be undone? What is the expected behaviour if it fails halfway?

For each answer, build the Gherkin scenario internally
When all phases are covered (or explicitly skipped), write the
```
.feature
```
file

Interview rules:

Ask one question at a time. Wait for the answer before continuing.
Keep questions concrete and provocative, not abstract. Instead of "are there error cases?" ask "what happens if the user submits the form while already logged in on another device?"
Stop a phase when: the user gave a concrete behaviour, explicitly excluded the case, or the next question would be redundant with a previous answer

Escape hatches — recognise these responses at any point:

User says	Behaviour
"I don't know yet" / "not sure"	Tag scenario `@pending` , continue to next phase
"doesn't matter" / "not relevant"	Tag case `@out-of-scope` with a brief note, continue
"move on" / "next" / "skip"	Close current phase, move to next
"that's enough" / "done"	End interview, write file

Output:

docs/specs/features/<domain>/<feature-name>.feature

After writing the file, suggest continuing with the superpowers flow:

"The feature spec is ready. To design HOW to build this, continue with the brainstorming skill."

为新功能从零开始进行需求调研。

流程：

请求用户用1-2句话描述功能的大致内容
进入访谈模式——每次只提一个问题，按以下顺序进行：

阶段	问题重点
正常流程	请逐步描述该功能的理想使用流程
角色	谁可以使用该功能？是否存在不同权限的角色？
输入验证	该功能接收哪些输入？哪些输入可能格式错误、为空或超出范围？
系统错误	哪些用户无法控制的情况会导致功能出错？（网络、数据库、第三方服务）
幂等性	如果重复执行该操作会发生什么？重复调用是否安全？
并发	如果两个用户同时触发该操作会发生什么？
回滚	该操作是否可以撤销？如果执行中途失败，预期行为是什么？

根据每个回答，在内部构建Gherkin场景
当所有阶段完成（或用户明确跳过）后，写入
```
.feature
```
文件

访谈规则：

一次只提一个问题，等待用户回答后再继续。
问题要具体且有针对性，避免抽象。比如不要问“是否有错误场景？”，而是问“如果用户在另一台设备已登录的情况下提交表单会发生什么？”
当以下情况发生时，结束当前阶段：用户给出了具体的行为说明、明确排除了该情况，或下一个问题与之前的回答重复

紧急退出机制——在任何阶段识别以下用户回复：

用户回复	处理方式
“我还不知道” / “不确定”	为场景添加 `@pending` 标签，继续下一阶段
“无所谓” / “不相关”	为该情况添加 `@out-of-scope` 标签并附上简短说明，继续下一阶段
“继续” / “下一个” / “跳过”	结束当前阶段，进入下一阶段
“够了” / “完成了”	结束访谈，写入文件

输出：

docs/specs/features/<domain>/<feature-name>.feature

写入文件后，建议用户继续Superpowers流程：

“功能规格已准备完成。如需设计实现方案，请继续使用brainstorming功能。”

/groundwork extend <feature-name>

/groundwork extend <feature-name>

Add new scenarios to an existing feature — typically edge cases discovered during use.

Flow:

Read the existing
```
.feature
```
file
Summarise the scenarios already covered (2-3 lines max)
Ask what new case the user discovered or wants to add
Enter focused interview mode — only ask about gaps not already covered
Append new scenarios to the file

Critical rule: Never modify existing scenarios. Append only.

After appending, suggest continuing with the superpowers flow:

"New scenarios added. If this changes the implementation approach, continue with the brainstorming skill to revisit the design."

为现有功能添加新场景——通常是在使用过程中发现的边缘情况。

流程：

读取现有的
```
.feature
```
文件
简要总结已覆盖的场景（最多2-3行）
询问用户发现或想要添加的新情况
进入聚焦访谈模式——只询问未覆盖的内容
将新场景追加到文件中

核心规则： 绝不修改现有场景，仅可追加。

追加完成后，建议用户继续Superpowers流程：

“已添加新场景。如果此变更影响实现方案，请继续使用brainstorming功能重新审视设计。”

/groundwork review [feature-name]

/groundwork review [feature-name]

Prepare

.feature

files as context for a Superpowers session.

Flow:

List all available
```
.feature
```
files under
```
docs/specs/features/
```
If no argument given, ask which features are relevant to the current session
Output a formatted context block ready to paste into Superpowers

将

.feature

文件准备为Superpowers会话可用的上下文。

流程：

列出
```
docs/specs/features/
```
下所有可用的
```
.feature
```
文件
如果未指定参数，询问用户当前会话相关的功能是哪些
输出可直接粘贴到Superpowers中的格式化上下文块

Gherkin writing rules

Gherkin编写规则

Granularity

粒度

Scenarios must describe observable behaviour, not implementation details or UI specifics.

gherkin

undefined

场景必须描述可观察行为，而非实现细节或UI特定内容。

gherkin

undefined

Wrong — fragile, breaks on every UI change

错误示例——易受影响，UI变更就会失效

When the user clicks the button with id "btn-submit" Then they see "Password incorrect" in red below the password field

When 用户点击ID为"btn-submit"的按钮 Then 他们会在密码字段下方看到红色的"密码错误"提示

Right — behavioural, survives refactoring

正确示例——基于行为，重构后依然有效

When the user attempts login with incorrect credentials Then the operation fails with an authentication error

undefined

When 用户尝试使用错误的凭据登录 Then 操作失败并返回身份验证错误

undefined

Interface type tag

接口类型标签

Every

.feature

file must have a tag on the

Feature:

line declaring the interface type. This is consumed by groundwork-verify to select the right toolchain.

gherkin

@api        # REST or GraphQL
@cli        # command-line interface
@web        # browser-based frontend

每个

.feature

文件必须在

Feature:

行添加一个标签，声明接口类型。 groundwork-verify会根据该标签选择合适的工具链。

gherkin

@api        # REST或GraphQL
@cli        # 命令行界面
@web        # 基于浏览器的前端

Scenario tags

场景标签

Tag	Meaning
`@pending`	Identified but behaviour not yet defined
`@out-of-scope`	Explicitly excluded — decision documented
`@wip`	In progress, not yet stable
`@critical`	Blocking — if this fails, the feature is not shippable

标签	含义
`@pending`	已识别但行为尚未定义
`@out-of-scope`	明确排除——决策已记录
`@wip`	进行中，尚未稳定
`@critical`	阻塞性——如果该场景失败，功能无法发布

Output format

输出格式

gherkin

@api
Feature: <feature name>
  <one-line description>

  Background:
    Given <shared precondition if any>

  @critical
  Scenario: <happy path name>
    Given <initial state>
    When <action>
    Then <observable outcome>
    And <additional outcome if needed>

  Scenario: <edge case name>
    ...

  @pending
  Scenario: <case not yet defined>
    # TODO: define expected behaviour

  @out-of-scope
  Scenario: <excluded case>
    # Decision: <brief reason>

gherkin

@api
Feature: <功能名称>
  <一行描述>

  Background:
    Given <如果有则填写共享前置条件>

  @critical
  Scenario: <正常流程名称>
    Given <初始状态>
    When <操作>
    Then <可观察结果>
    And <如有需要可添加额外结果>

  Scenario: <边缘情况名称>
    ...

  @pending
  Scenario: <尚未定义的情况>
    # TODO: 定义预期行为

  @out-of-scope
  Scenario: <已排除的情况>
    # 决策：<简短原因>

File structure

文件结构

docs/
  specs/
    CONVENTIONS.md
    features/
      <domain>/
      <feature-name>.feature

If the

docs/specs/

directory doesn't exist, create it. If

CONVENTIONS.md

doesn't exist, offer to create it after the first

.feature

file is written.

docs/
  specs/
    CONVENTIONS.md
    features/
      <domain>/
      <feature-name>.feature

如果

docs/specs/

目录不存在，则创建它。如果

CONVENTIONS.md

不存在，在生成第一个

.feature

文件后主动提出创建该文件。

Common mistakes

常见错误

Mistake	Fix
Writing UI-specific steps ("clicks button with id btn-submit")	Write behavioural steps ("attempts login with incorrect credentials")
Forgetting the interface tag ( `@api` , `@cli` , `@web` ) on Feature line	Always ask which interface the feature exposes — groundwork-verify depends on it
Asking multiple questions at once	One question per message — wait for the answer before continuing
Skipping phases because "it's a simple feature"	Run all phases — skip only when the user explicitly says "skip" or "move on"
Modifying existing scenarios in `/groundwork extend`	Append only — never change existing scenarios
Writing implementation details in scenarios	Scenarios describe observable behaviour, not how the system achieves it
Discussing architecture or tech choices during discovery	Discovery captures WHAT, not HOW — redirect architecture questions to brainstorming
Skipping the brainstorming handoff after writing the feature file	Always suggest continuing with brainstorming to design the implementation

错误	修复方案
编写UI特定步骤（如“点击ID为btn-submit的按钮”）	编写基于行为的步骤（如“尝试使用错误凭据登录”）
在Feature行忘记添加接口标签（ `@api` 、 `@cli` 、 `@web` ）	始终询问功能暴露的接口类型——groundwork-verify依赖该信息
一次提出多个问题	每次只提一个问题——等待用户回答后再继续
因为“功能很简单”而跳过某些阶段	执行所有阶段——仅当用户明确说“跳过”或“继续”时才跳过
在 `/groundwork extend` 中修改现有场景	仅可追加——绝不修改现有场景
在场景中编写实现细节	场景应描述可观察行为，而非系统实现方式
在调研过程中讨论架构或技术选型	调研环节只记录“要实现什么”，不涉及“如何实现”——将架构相关问题引导至头脑风暴环节
生成功能文件后未引导至头脑风暴环节	始终建议用户继续使用头脑风暴功能设计实现方案