/distill

description: "Creates E2E acceptance tests in Given-When-Then format from requirements and architecture. Use when preparing executable specifications before implementation."
argument-hint: "[story-id] - Optional: --test-framework=[cucumber|specflow|pytest-bdd] --integration=[real-services|mocks]"

NW-DISTILL: Acceptance Test Creation and Business Validation

**Wave**: DISTILL (wave 5 of 6) | **Agent**: Quinn (nw-acceptance-designer)

Overview

Orchestrate acceptance test creation from prior wave artifacts, then gate the result through parallel reviews before handoff to DELIVER. You (main Claude instance) are the orchestrator. You dispatch agents and enforce gates.

The AT-completeness gate, MAX-PBT mandate, and Mandate-12 step-reuse metric are advisory.

REVIEW GATE SUMMARY (read this first)

After the acceptance designer produces scenarios, you MUST dispatch 4 parallel reviewers if scenario count exceeds 3 (Eclipse + Architect + Forge + Sentinel). Sentinel (`@nw-acceptance-designer-reviewer`) is the structural-correctness reviewer — it ALWAYS dispatches even on fast-path or under `rigor.reviewer_model: "skip"` (which only skips scale-sensitive cost-driven reviewers). This is the single most important orchestration step in DISTILL. The procedure is: dispatch designer -> count scenarios -> dispatch 4 reviewers in parallel -> AND-gate results -> handoff. Details in Phase 3 below.

Phase 1: Decisions and Context

Interactive Decision Points

Decision 1: Feature Scope

**Question**: What is the scope of this feature? **Options**: 1. Core feature -- primary application functionality 2. Extension -- modular add-on or integration 3. Bug fix -- regression tests for a known defect

Decision 2: Test Framework

**Question**: Which test framework to use? **Options**: 1. pytest-bdd -- Python BDD framework 2. Cucumber -- Ruby/JS BDD framework 3. SpecFlow -- .NET BDD framework 4. Custom -- user provides details

Decision 3: Integration Approach

**Question**: How should integration tests connect to services? **Options**: 1. Real services -- test against actual running services 2. Test containers -- ephemeral containers for dependencies 3. Mocks for external only -- real internal, mocked external services

Decision 4: Infrastructure Testing

**Question**: Should acceptance tests cover infrastructure concerns? **Options**: 1. Yes -- include CI/CD validation, deployment smoke tests 2. No -- functional acceptance tests only

Prior Wave Consultation

DISTILL is the conjunction point — it reads all three SSOT dimensions plus the feature delta.

**SSOT (all three dimensions):** 1. **Journeys** (behavior): Read `docs/product/journeys/{name}.yaml` — extract embedded Gherkin as starting scenarios, identify integration checkpoints and failure_modes 2. **Architecture** (structure): Read `docs/product/architecture/brief.md` — identify driving ports (from `## For Acceptance Designer` section) for port-entry test scenarios 3. **KPI contracts** (observability): Read `docs/product/kpi-contracts.yaml` — identify which behaviors need `@kpi` tagged scenarios (soft gate — warn if missing, proceed)

**Feature delta:** 4. **DISCUSS**: Read from `docs/feature/{feature-id}/discuss/`:

• `user-stories.md` (scope boundary — generate tests for THIS feature's stories only) | `story-map.md` | `wave-decisions.md`

5. **DEVOPS** (test environment): Read from `docs/feature/{feature-id}/devops/`:

• `platform-architecture.md` | `ci-cd-pipeline.md` | `wave-decisions.md`

**Scope rule**: DISTILL generates tests for the behaviors described in `user-stories.md`, not for the entire SSOT. The SSOT provides context (which port to enter through, which KPI to verify) but the scope is bounded by the feature delta.

**READING ENFORCEMENT**: Read every file above using the Read tool. Output confirmation checklist (`+ {file}` for each read, `- {file} (not found)` for missing). Do NOT skip files that exist.

**Fallback**: If `docs/product/` does not exist, fall back to `docs/feature/{feature-id}/` for all inputs (old model).

Graceful Degradation

• **KPI contracts missing**: Log warning: "KPI contracts missing — acceptance tests cover behavior only, not observability." Proceed without `@kpi` scenarios.
• **DEVOPS missing**: Log warning, use default environment matrix (clean, with-pre-commit, with-stale-config). Proceed.
• **DISCUSS missing**: Log warning, derive AC from architecture. Skip story-to-scenario traceability. Proceed.
• **Architecture SSOT missing**: BLOCK. Ask user to identify driving ports. Without them, hexagonal boundary is unverifiable.

Rigor Profile

Read rigor config from `.nwave/des-config.json` (key: `rigor`). If absent, use standard defaults.

• `agent_model`: Pass as `model` to acceptance designer. If `"inherit"`, omit.
• `reviewer_model`: Pass as `model` to scale-sensitive cost-driven reviewers (Eclipse / Architect / Forge). If `"skip"`, skip those three only — **Sentinel (`@nw-acceptance-designer-reviewer`) ALWAYS dispatches** because it is the structural-correctness reviewer (Gherkin antipatterns, hexagonal boundary, contract drift); silent skip masks the bug class issue #52 was filed for.

Wave-Decision Reconciliation

BEFORE dispatching the acceptance designer: 1. Read ALL `wave-decisions.md` files from prior waves 2. Check for contradictions between DISCUSS, DESIGN, and DEVOPS decisions 3. If ANY contradiction: list them all, BLOCK until user resolves each one 4. If zero contradictions: log "Reconciliation passed" and proceed

Phase 2: Dispatch Acceptance Designer

@nw-acceptance-designer

Execute \*create-acceptance-tests for {feature-id}.

**Prompt must include:**

• All prior wave context read in Phase 1
• Decisions 1-4 configuration
• Instruction to load skills at `~/.claude/skills/nw-{skill-name}/SKILL.md` — explicitly include `nw-acceptance-designer` skills, `nw-bdd-methodology`, `nw-test-design-mandates`, and `nw-at-completeness-check`
• **MAX-PBT + param