distill

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Distill — reverse-engineer Gherkin feature files from existing code.

Use this to bring existing codebases into the Beat workflow. The output is draft

.feature

files that describe current behavior (not aspirational), verified independently by

/beat:verify

<decision_boundary>

Use for:

Extracting BDD specs from an existing codebase that doesn't have feature files yet
Bringing a module, directory, or functionality into the Beat workflow retroactively
Generating draft
```
.feature
```
files that describe what the code currently does

NOT for:

Designing new behavior or features (use
```
/beat:design
```
)
Writing aspirational specs for code that doesn't exist yet (use
```
/beat:design
```
)
Greenfield projects with no existing code to distill
Exploring ideas or thinking through a problem (use
```
/beat:explore
```
)

Trigger examples:

"Distill the auth module into feature files" / "Extract specs from existing code" / "Bring this codebase into Beat"
Should NOT trigger: "design a new feature" / "write specs for something we want to build" / "explore this idea"

</decision_boundary>

<HARD-GATE> Before writing any artifact files: you MUST invoke superpowers:using-git-worktrees. Distilled artifacts live in a change container that may later flow through plan → apply → archive. Worktree isolation ensures they don't contaminate the main workspace.

If a prerequisite skill is unavailable (not installed), continue with fallback — but NEVER skip because you judged it unnecessary. </HARD-GATE>

Prerequisites (invoke before proceeding)

Superpower	When	Priority
using-git-worktrees	Before first file write	MUST

If a superpower is unavailable (skill not installed), skip and continue.

Distill——从现有代码反向生成Gherkin feature文件。

使用该功能可将现有代码库纳入Beat工作流。输出为描述当前行为（而非预期行为）的草稿

.feature

文件，可通过

/beat:verify

独立验证。

<decision_boundary>

适用场景：

从尚未拥有feature文件的现有代码库中提取BDD规格
追溯性地将某个模块、目录或功能纳入Beat工作流
生成描述代码当前实际行为的草稿
```
.feature
```
文件

不适用场景：

设计新行为或新功能（请使用
```
/beat:design
```
）
为尚未存在的代码编写预期规格（请使用
```
/beat:design
```
）
无现有代码可提炼的全新项目
探索想法或梳理问题（请使用
```
/beat:explore
```
）

触发示例：

"将认证模块提炼为feature文件" / "从现有代码中提取规格" / "将该代码库纳入Beat"
不应触发的场景："设计新功能" / "为我们想要构建的内容编写规格" / "探索这个想法"

</decision_boundary>

<HARD-GATE> 在编写任何工件文件之前：必须调用superpowers:using-git-worktrees。提炼出的工件存放在变更容器中，后续可进入plan → apply → archive流程。工作树隔离可确保它们不会污染主工作区。

如果必备技能不可用（未安装），请使用回退方案继续——但绝不能因你认为不必要而跳过该步骤。 </HARD-GATE>

前置条件（执行前需调用）

Superpower	时机	优先级
using-git-worktrees	首次写入文件前	必须执行

如果某个superpower不可用（技能未安装），请跳过并继续。

Rationalization Prevention

避免合理化借口

Thought	Reality
"I don't need a worktree for just writing feature files"	Distilled artifacts flow into plan/apply/archive. Without isolation, they won't carry forward correctly.
"The code is simple, I can verify the scenarios myself"	Self-verification of distilled specs is explicitly forbidden. Always use `/beat:verify` for independent accuracy checking.
"I'll skip scanning existing features, this is a new area"	Existing features may already cover this behavior. Distilling duplicates creates maintenance burden.
"These scenarios are obviously correct, verification is overkill"	Distill extracts specs from code — the most likely error is describing aspirational behavior instead of current behavior. Verification catches this.
"I'll commit later, let me just generate the files first"	Uncommitted artifacts can be lost. Commit before presenting to the user, matching design's behavior.

错误想法	实际情况
"只是写feature文件，不需要工作树"	提炼出的工件会进入plan/apply/archive流程。若无隔离，它们将无法正确流转。
"代码很简单，我可以自己验证场景"	明确禁止自行验证提炼出的规格。必须始终使用 `/beat:verify` 进行独立准确性检查。
"我会跳过扫描现有feature，这是新领域"	现有feature可能已覆盖该行为。重复提炼会增加维护负担。
"这些场景显然正确，验证纯属多余"	Distill从代码中提取规格——最可能出现的错误是描述预期行为而非当前行为。验证可发现此类问题。
"我稍后再提交，先生成文件再说"	未提交的工件可能丢失。提交后再呈现给用户，与设计行为保持一致。

Red Flags — STOP if you catch yourself:

警示信号——如果发现自己有以下行为，请立即停止：

Writing any file before invoking using-git-worktrees
Writing scenarios that describe desired behavior instead of current behavior
Skipping the existing feature scan
Claiming verification passed without running
```
/beat:verify
```
Finishing without committing artifacts
Writing Gherkin scenarios that contain internal method names, numeric thresholds, or implementation constants
Thinking "I know the code well enough to skip verification"

在调用using-git-worktrees之前编写任何文件
编写描述预期行为而非当前行为的场景
跳过现有feature扫描
未运行
```
/beat:verify
```
就声称验证通过
未提交工件就完成操作
编写包含内部方法名、数值阈值或实现常量的Gherkin场景
认为"我对代码足够了解，可以跳过验证"

Process Flow

流程

dot

digraph distill {
    "Ask for scope" [shape=box];
    "Invoke using-git-worktrees" [shape=box, style=bold];
    "Read and understand code" [shape=box];
    "Scan existing features" [shape=box];
    "Scope already covered?" [shape=diamond];
    "STOP: inform user" [shape=box, style=dashed];
    "Create change container" [shape=box];
    "Generate draft artifacts" [shape=box];
    "Commit artifacts" [shape=box];
    "Present to user" [shape=doublecircle];

    "Ask for scope" -> "Invoke using-git-worktrees";
    "Invoke using-git-worktrees" -> "Read and understand code";
    "Read and understand code" -> "Scan existing features";
    "Scan existing features" -> "Scope already covered?";
    "Scope already covered?" -> "STOP: inform user" [label="yes"];
    "Scope already covered?" -> "Create change container" [label="no"];
    "Create change container" -> "Generate draft artifacts";
    "Generate draft artifacts" -> "Commit artifacts";
    "Commit artifacts" -> "Present to user";
}

Input: User specifies the code scope to distill (module, directory, or functionality).

Steps

Ask for scope

If not specified, use AskUserQuestion tool:

"What code do you want to distill into BDD specs? Specify a module, directory, or describe the functionality."
Ensure worktree isolation
Invoke
```
using-git-worktrees
```
before reading or writing any files.
Read and understand the code

Read the specified code. Map out:
- User-visible behaviors (functionality)
- Edge cases handled
- Error conditions
- Existing tests (if any) that reveal behavior
Scan existing features
Scan
```
beat/features/**/*.feature
```
and
```
beat/changes/*/features/*.feature
```
(excluding archive):
- Read
```
Feature:
```
  and
```
Scenario:
```
  lines to map existing coverage
- Deep-read only features that overlap with the distill scope
- Note which behaviors are already covered — do NOT distill duplicates
- If the scope is entirely covered: inform user and STOP

Create a change container

Create

beat/changes/distill-<scope-name>/

with

status.yaml

(schema:

references/status-schema.md

yaml

name: distill-<scope-name>
created: YYYY-MM-DD
phase: new
source: distill
pipeline:
  proposal: { status: pending }
  gherkin: { status: pending }
  design: { status: pending }
  tasks: { status: pending }

Generate draft artifacts
Read
```
beat/config.yaml
```
if it exists (schema:
```
references/config-schema.md
```
). Use
```
language
```
for artifact output language, inject
```
context
```
as project background, and apply matching
```
rules
```
per artifact type (e.g.,
```
rules.gherkin
```
,
```
rules.proposal
```
,
```
rules.design
```
).
features/*.feature (mandatory):
- Read
```
references/feature-writing.md
```
  for conventions on description blocks, scenario organization, and review checklist
- Write feature files describing CURRENT behavior (not desired behavior)
- Each scenario must accurately reflect what the code actually does
- Use tags:
```
@distilled
```
  (always), plus
```
@happy-path
```
  ,
```
@error-handling
```
  ,
```
@edge-case
```
- Every scenario MUST have a testing layer tag (
```
@e2e
```
  or
```
@behavior
```
  , default
```
@behavior
```
  )
- If behavior is ambiguous, note it as uncertain rather than guessing
proposal.md (optional):
- If the purpose is clear from code/docs: write a brief "why this exists" proposal
- Sections:
```
## Why
```
  ,
```
## What Changes
```
  ,
```
## Impact
```
design.md (optional):
- Document the current technical architecture and key decisions visible in the code
- Sections:
```
## Approach
```
  ,
```
## Key Decisions
```
  ,
```
## Components
```
Update
```
status.yaml
```
for each artifact created. Set phase to the latest completed spec artifact.
Commit artifacts
Commit all change artifacts:
```
git add beat/changes/distill-<scope-name>/ && git commit
```
Use a descriptive message: "distill(<scope>): extract BDD specs from existing code"

Present to user for review

Show:

All generated feature files (summary of scenarios per feature)
Any remaining uncertainties about behavior
Existing features that overlap (from step 4 scan)

## Distill Complete: distill-<scope-name>

Created:
- features/*.feature (N scenarios across M files)
- proposal.md (or skipped)
- design.md (or skipped)

Uncertainties: [list any ambiguous behaviors]

Next steps:
- Review the draft feature files for accuracy
- Run `/beat:verify` to independently verify scenarios match code behavior
- Then `/beat:plan` → `/beat:apply` for future changes using the normal BDD flow

Distill vs Normal Flow

Normal:  Spec -> Code   (write spec first, then implement)
Distill: Code -> Spec   (extract spec from existing code)
              |
         /beat:verify confirms accuracy (source: distill → accuracy mode)
              |
         Future changes use normal BDD flow

dot

digraph distill {
    "Ask for scope" [shape=box];
    "Invoke using-git-worktrees" [shape=box, style=bold];
    "Read and understand code" [shape=box];
    "Scan existing features" [shape=box];
    "Scope already covered?" [shape=diamond];
    "STOP: inform user" [shape=box, style=dashed];
    "Create change container" [shape=box];
    "Generate draft artifacts" [shape=box];
    "Commit artifacts" [shape=box];
    "Present to user" [shape=doublecircle];

    "Ask for scope" -> "Invoke using-git-worktrees";
    "Invoke using-git-worktrees" -> "Read and understand code";
    "Read and understand code" -> "Scan existing features";
    "Scan existing features" -> "Scope already covered?";
    "Scope already covered?" -> "STOP: inform user" [label="yes"];
    "Scope already covered?" -> "Create change container" [label="no"];
    "Create change container" -> "Generate draft artifacts";
    "Generate draft artifacts" -> "Commit artifacts";
    "Commit artifacts" -> "Present to user";
}

输入：用户指定要提炼的代码范围（模块、目录或功能）。

步骤

确认范围

如果未指定范围，请使用AskUserQuestion工具：

"你想要将哪些代码提炼为BDD规格？请指定模块、目录或描述相关功能。"
确保工作树隔离
在读取或写入任何文件之前，调用
```
using-git-worktrees
```
。
读取并理解代码

读取指定代码，梳理：
- 用户可见的行为（功能）
- 处理的边缘情况
- 错误条件
- 现有测试（如有）所体现的行为
扫描现有feature
扫描
```
beat/features/**/*.feature
```
和
```
beat/changes/*/features/*.feature
```
（排除归档目录）：
- 读取
```
Feature:
```
  和
```
Scenario:
```
  行以梳理现有覆盖范围
- 仅深入阅读与提炼范围重叠的feature
- 记录已覆盖的行为——请勿重复提炼
- 如果范围已完全覆盖：告知用户并停止操作

创建变更容器

创建

beat/changes/distill-<scope-name>/

目录及

status.yaml

文件（ schema：

references/status-schema.md

）：

yaml

name: distill-<scope-name>
created: YYYY-MM-DD
phase: new
source: distill
pipeline:
  proposal: { status: pending }
  gherkin: { status: pending }
  design: { status: pending }
  tasks: { status: pending }

生成草稿工件
如果存在
```
beat/config.yaml
```
，请读取该文件（schema：
```
references/config-schema.md
```
）。使用
```
language
```
指定工件输出语言，注入
```
context
```
作为项目背景，并根据工件类型应用匹配的
```
rules
```
（例如
```
rules.gherkin
```
、
```
rules.proposal
```
、
```
rules.design
```
）。
features/*.feature（必填）：
- 阅读
```
references/feature-writing.md
```
  了解描述块、场景组织和审核清单的约定
- 编写描述当前行为（而非预期行为）的feature文件
- 每个场景必须准确反映代码的实际行为
- 使用标签：
```
@distilled
```
  （必填），外加
```
@happy-path
```
  、
```
@error-handling
```
  、
```
@edge-case
```
- 每个场景必须包含测试层标签（
```
@e2e
```
  或
```
@behavior
```
  ，默认
```
@behavior
```
  ）
- 如果行为不明确，请标注为不确定，而非猜测
proposal.md（可选）：
- 如果从代码/文档中可明确其用途：编写简短的“存在意义”提案
- 章节：
```
## 原因
```
  、
```
## 变更内容
```
  、
```
## 影响
```
design.md（可选）：
- 记录代码中可见的当前技术架构和关键决策
- 章节：
```
## 实现思路
```
  、
```
## 关键决策
```
  、
```
## 组件
```
为每个创建的工件更新
```
status.yaml
```
，将阶段设置为最新完成的规格工件。
提交工件
提交所有变更工件：
```
git add beat/changes/distill-<scope-name>/ && git commit
```
使用描述性提交信息："distill(<scope>): extract BDD specs from existing code"

呈现给用户审核

展示：

所有生成的feature文件（每个feature的场景摘要）
关于行为的剩余不确定性
与范围重叠的现有feature（来自步骤4的扫描）

## 提炼完成：distill-<scope-name>

创建的内容：
- features/*.feature（M个文件共N个场景）
- proposal.md（或已跳过）
- design.md（或已跳过）

不确定项：[列出所有模糊行为]

下一步：
- 审核草稿feature文件的准确性
- 运行`/beat:verify`独立验证场景是否匹配代码行为
- 随后使用常规BDD流程执行`/beat:plan` → `/beat:apply`以进行后续变更

Distill与常规流程对比

常规流程:  规格 → 代码   （先写规格，再实现）
Distill流程: 代码 → 规格   （从现有代码提取规格）
              |
         /beat:verify 确认准确性（来源：distill → 准确性模式）
              |
         后续变更使用常规BDD流程