/nw-spike

name: nw-spike
description: "Runs a timeboxed PROBE to validate one core assumption, then optionally PROMOTES the probe into a walking skeleton — the first e2e thin slice of the feature, committed and demo-able. Use after DISCUSS when the feature involves a new mechanism, performance requirement, or external integration."
user-invocable: true
argument-hint: "[feature-description] - Example: \"wave-matrix -- derive feature status from pytest + filesystem\""

NW-SPIKE: Probe → Walking Skeleton

**Wave**: SPIKE (between DISCUSS and DESIGN) | **Agent**: Attila (nw-software-crafter) | **Command**: `/nw-spike`

Overview

Execute a two-phase wave that turns a risky assumption into visible, iterable value as fast as possible:

1. **PROBE** — quick throwaway validation of one core assumption (30-60 min, code in `/tmp/`) 2. **PROMOTION GATE** (interactive) — ask the user whether to promote the probe 3. **WALKING SKELETON** — refactor the probe into an end-to-end thin slice committed to the repository (1-3 h, code in `src/` + 1 acceptance test)

The PROBE answers "does the mechanism work?". The WALKING SKELETON answers "can a user see it working end-to-end?". You never throw away working validated code — you promote it and iterate.

When to use

The spike is needed when the feature introduces:

• A new mechanism never tried in this codebase
• A performance requirement that cannot be validated by reasoning alone
• An external integration with unknown behaviour

If none of the above apply, skip SPIKE and go to DESIGN.

Prior Wave Consultation

1. **DISCUSS artifacts**: Read `docs/feature/{feature-id}/discuss/` (required)

• `user-stories.md` — scope and acceptance criteria
• `wave-decisions.md` — constraints and assumptions to test

2. **DIVERGE artifacts**: Read `docs/feature/{feature-id}/diverge/recommendation.md` (if present)

Interactive decision points (Phase 1 entry)

Decision 1: Probe scope

**Question**: What is the ONE assumption you need to validate? **Examples**:

• "Can we parse pytest output reliably in <5 seconds?"
• "Can the CEL library evaluate 100 expressions in <1 second?"
• "Can we write to `.git/hooks/` from a subprocess without corruption?"

Decision 2: Performance budget

**Question**: What is the timing constraint? (Enter "none" if mechanism validation only) **Examples**:

• "<5 seconds end-to-end"
• "<100ms per operation"
• "Handle 10K items without OOM"

Decision 3: End-to-end path preview

**Question**: If this probe works, what would the thinnest end-to-end slice look like? Capture the rough path: `user-facing entry → business logic → persistence/services → user-visible output`. This is **not** a commitment — it's context for the promotion gate later.

Phase 1 — PROBE

Throwaway validation of the assumption.

Agent invocation

@nw-software-crafter

Execute PROBE for "{feature-description}".

**Probe question**: {Decision 1 answer} **Performance budget**: {Decision 2 answer} **Target e2e path (for later)**: {Decision 3 answer}

**Rules**:

• Code goes in `/tmp/spike_{feature_id}/`. Never in `src/`.
• Max 1 hour. No tests, no types, no error handling, no abstractions.
• One file preferred. Two files maximum.
• Use `time.perf_counter()` for timing.
• Print results to stdout.

**After probe completes**: 1. Write findings to `docs/feature/{feature-id}/spike/findings.md` — binary verdict (WORKS / DOESN'T WORK), timing, edge cases, design implications. 2. Do **not** delete the probe code yet — wait for the promotion gate. 3. Report verdict and ask the orchestrator to run the promotion gate.

Phase 2 — PROMOTION GATE (interactive)

Run this gate **only after** the probe completes and findings.md is written.

Present the user with three choices:

| Choice | When to pick | Outcome | |---|---|---| | **PROMOTE** | Probe verdict is WORKS and the mechanism is worth building on | Proceed to Phase 3 — walking skeleton | | **DISCARD** | Probe verdict is WORKS but not worth pursuing (findings are enough) | Delete `/tmp/spike_{feature_id}/`. Commit `findings.md`. Hand off to DESIGN. | | **PIVOT** | Probe verdict is DOESN'T WORK or revealed a better approach | Delete probe code. Annotate `findings.md` with the pivot. Either loop back to DISCUSS or run a second probe. |

**Default**: if the probe verdict is WORKS and no reason to stop, recommend PROMOTE but let the user override.

Record the promotion decision in `docs/feature/{feature-id}/spike/wave-decisions.md` as an explicit wave decision with rationale.

Phase 3 — WALKING SKELETON (only if PROMOTE)

Refactor the probe into the thinnest end-to-end slice that is committed, tested, and demo-able.

Definition of Done (walking skeleton)

1. **End-to-end path**: the slice enters from a real user-facing entry point (CLI command, HTTP endpoint, UI action, hook) and exits at a real user-visible output (stdout, HTTP response, rendered screen, persisted file). Every layer in between is exercised — **no layer is mocked** unless that layer is an external paid service classified as costly in DISTILL's Walking Skeleton Strategy (then use the fake/contract test pattern). 2. **One acceptance test**: a `@walking_skeleton @driving_port` tagged scenario in `tests/{test-type-path}/{feature-id}/acceptance/walking-skeleton.feature`. The scenario MUST be green before hand-off. 3. **Production location**: code lives under `src/{production-path}/`, not in `/tmp/`. Minimal module skeleton is fine — no premature abstractions, no features beyond the walking skeleton. 4. **Committed**: the walking skeleton commit message is `feat({feature-id}): walking skeleton — {one-line description}`. 5. **Demo-able**: running the single acceptance test (or the real entry-point command) produces visible output that matches the user story from DISCUSS. 6. **Back-propagation**: if building the skeleton reveals a contradiction with DISCUSS or DESIGN, write the contradiction to `docs/feature/{feature-id}/spike/upstream-issues.md` and stop