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 GLOSSARY.md at the project root (path: references/project-layout.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. If the user explicitly asks to skip the worktree, say that the change container will be written and committed on the current branch, confirm once, then proceed there — never imply an isolation you don't have. </HARD-GATE>

Prerequisites (invoke before proceeding)

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

Rationalization Prevention

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
• Writing scenarios that use project-specific domain terms not defined in GLOSSARY.md
• Writing a Key Decision in design.md without running the three-condition ADR gate
• Inventing rationale for a recovered decision instead of marking it unverified or asking
• Skipping the spec self-review because the scenarios "came straight from the code"
• Telling the user to run /beat:plan or /beat:apply on the distill change itself (there is nothing to implement)
• Thinking "I know the code well enough to skip verification"

Process Flow

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];
    "Glossary check\n(terms → GLOSSARY.md)" [shape=box, style=bold];
    "Generate draft artifacts\n(self-review each)" [shape=box];
    "design.md included?" [shape=diamond];
    "ADR gate\n(design.md Key Decisions)" [shape=box, style=bold];
    "Offer module README\n(Layer 3, optional)" [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" -> "Glossary check\n(terms → GLOSSARY.md)";
    "Glossary check\n(terms → GLOSSARY.md)" -> "Generate draft artifacts\n(self-review each)";
    "Generate draft artifacts\n(self-review each)" -> "design.md included?";
    "design.md included?" -> "ADR gate\n(design.md Key Decisions)" [label="yes"];
    "design.md included?" -> "Offer module README\n(Layer 3, optional)" [label="no"];
    "ADR gate\n(design.md Key Decisions)" -> "Offer module README\n(Layer 3, optional)";
    "Offer module README\n(Layer 3, optional)" -> "Commit artifacts";
    "Commit artifacts" -> "Present to user";
}

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

Steps

1. 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."

2. Ensure worktree isolation

   Invoke using-git-worktrees before reading or writing any files.

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

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

5. Create a change container

   Create beat/changes/distill-<scope-name>/ with status.yaml (schema: references/status-schema.md):

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

   tasks is skipped because a distill change describes current behavior — there is nothing to implement. Future changes to this area get their own change containers via the normal /beat:design → /beat:plan → /beat:apply flow.

6. 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).

   Glossary check (Layer 1) — before writing feature files:

   Read GLOSSARY.md if it exists (schema: references/context-format.md). Create it lazily when the first term is added — never preemptively.

   Distill is often the first time an established codebase builds its glossary, and the code itself is the source. For each project-specific term that will appear in scenarios, adapt the four challenges from references/context-format.md and update GLOSSARY.md inline as terms resolve (never batch). Insert each entry where "Where a new entry goes" in references/context-format.md says — inside its ## <group> section (or ## Language), never appended after ## Flagged ambiguities; when creating the file, write the full skeleton first:

   1. Against the glossary — the term conflicts with an existing entry? Surface, resolve, update.
   2. Sharpen fuzzy — the code uses synonyms for one concept (e.g. user/account/member for the same entity)? Pick the canonical word, list the others as _Avoid_.
   3. Stress-test against code — probe term boundaries with the edge cases the code actually handles; name the boundary.
   4. Cross-reference docs — README/comments/docs use a term differently from the code? Surface it and ask the user which is canonical.

   Every project-specific term used in scenarios MUST exist in GLOSSARY.md before the scenario is written. Bold terms in scenarios are the canonical form (see references/feature-writing.md). If a term's meaning is genuinely uncertain from code alone, ask the user rather than guessing.

   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
   • If you choose not to write it: set proposal: { status: skipped } in status.yaml — never leave it pending (archive warns on pending artifacts)

   design.md (optional):

   • Document the current technical architecture and key decisions visible in the code
   • Sections: ## Approach, ## Key Decisions, ## Components
   • ADR gate — for each Key Decision recovered from the code, run the three-condition check from references/adr-format.md:
     1. Hard to reverse?
     2. Surprising without context?
     3. Result of a real trade-off? Recovered decisions are prime candidates — "surprising without context" is exactly what code archaeology surfaces. Caveat: the code shows what was decided, not why. Take rationale from evidence (commit history, comments, docs) or from the user; if neither is available, record the decision with rationale marked unverified (e.g. "Rationale unconfirmed — recovered from code"). Never invent a why. If all three hold, use AskUserQuestion tool: "This recovered decision meets the ADR gate. Lift it into docs/adr/?" On Yes, follow "Before writing an ADR" in references/adr-format.md (apply config rules.adr; use the project's docs/adr/TEMPLATE.md if it exists, otherwise Beat's front-matter template with source: beat/changes/distill-<scope-name>), write the 1-3 sentence ADR, incrementing the highest existing number. On No, continue. Create docs/adr/ lazily — only on first ADR. Step 7 commits the ADR with the change.
   • If you choose not to write design.md: set design: { status: skipped } in status.yaml — never leave it pending

   Spec self-review (after writing each artifact):

   Re-read the artifact with fresh eyes and check:

   1. Placeholder scan — any TBD, TODO, incomplete sections, vague descriptions?
   2. Internal consistency — do sections contradict each other? Do scenarios contradict the proposal/design?
   3. Scope check — does the artifact stay within the distill scope, or did it drift into adjacent behavior?
   4. Ambiguity check — could any scenario be read two different ways? If so, pick the reading the code supports and make it explicit.

   Fix issues inline. No need to re-review the fix — just fix and move on.

   Update status.yaml for each artifact created, and mark optional artifacts you chose not to create as skipped. Set phase to the latest completed spec artifact.

   Module README offer (Layer 3, optional):

   If the distilled scope is a module (its own directory with a public interface) and it has no README.md, offer once to scaffold one per references/architecture-format.md. If beat/ARCHITECTURE.md exists and is missing this module's row, offer to add it. Advisory — the user may decline; never block.

7. Lint and commit artifacts

   Run node <skill-dir>/scripts/lint-features.mjs beat/changes/<name>/features/*.feature and node <skill-dir>/scripts/validate-beat.mjs --file beat/changes/<name>/status.yaml (see references/lint-tools.md); fix every error before committing. Distilled scenarios have no tests yet, so @covered-by warnings are expected here.

   Commit the change directory and every living-documentation file this run wrote or modified — they are one unit of work:

   git add beat/changes/distill-<scope-name>/
   git add docs/adr/NNNN-<slug>.md   # each ADR from the ADR gate, by file name
   git add docs/adr/<index-file>     # only if the project keeps an ADR index there and this run updated it
   git add GLOSSARY.md           # glossary entries from the glossary check
   git add beat/ARCHITECTURE.md      # if the hub row was added
   git add <module>/README.md        # if the module README scaffold was accepted
   git commit

   Stage files by name, never docs/adr/ as a directory: a path is staged when git status shows it and this run wrote it; a path that is absent, unchanged, or was modified by the user outside this run stays unstaged.

   Use a descriptive message: "distill(<scope>): extract BDD specs from existing code"

8. 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)
   
   Glossary: N terms added to GLOSSARY.md (or "no new terms")
   ADRs: N written to docs/adr/ (or "none qualified")
   
   Uncertainties: [list any ambiguous behaviors]
   
   Next steps:
   - Review the draft feature files for accuracy
   - Run `/beat:verify` to independently verify scenarios match code behavior (accuracy mode)
   - Run `/beat:archive` to sync verified features into `beat/features/` living documentation
   - Future changes to this area use the normal flow: `/beat:design` → `/beat:plan` → `/beat:apply`

   Then end with the handoff block from references/handoff-report.md (next: /beat:verify <name>).

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)
              |
         /beat:archive syncs features into living documentation
              |
         Future changes use normal BDD flow (new change container)