distill

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>

Before writing feature files: you MUST run the glossary check (see step 6) and ensure every project-specific term used in scenarios is defined in beat/CONTEXT.md. Create the glossary lazily — only when the first term is added.

After writing each artifact: you MUST run the four-check spec self-review (placeholder / consistency / scope / ambiguity). Fix issues inline.

While writing design.md: you MUST run the three-condition ADR gate (hard-to-reverse + surprising + real trade-off — see references/adr-format.md) on each Key Decision recovered from the code. When all three hold, offer to lift it into docs/adr/. The user may decline. NEVER invent rationale the code doesn't show — mark it unverified or ask the user.

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

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.

Rationalization Prevention

Thought	Reality
"I don't need a worktree for just writing feature files"	Distilled artifacts flow through verify and 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.
"The terms are already in the code, no need for a glossary"	Code shows usage, not meaning. Distill is the moment an established codebase gets its glossary — entries are two lines, add them inline.
"I can't know why this decision was made, so no ADR"	You can't invent the why, but you can record the what and ask. Run the gate; mark unverified rationale as unverified instead of skipping.
"Spec self-review is overkill, the scenarios came straight from code"	Reading code ≠ describing it accurately. The four checks catch placeholders, contradictions, and ambiguities in 30 seconds.