/smoke-test

name: smoke-test
description: "Goal-driven smoke test for the feature just implemented. Drives a browser (UI) or hits the running service (backend), both, when full-stack. Tests every behaviour acceptance criteria define plus exploratory edges, catches console errors / network failures / a11y issues / contract violations / auth leaks / missing observability, fixes every gap or bug it finds, then re-runs until clean. Captures the successful trajectory as a permanent test before declaring done. Use after implementation and after figma-matcher (when UI), before /flagrare:wrap-up. Triggers when the user says 'smoke test', 'does this actually work', 'test the feature', 'validate this', 'launch the app and test', 'make sure nothing is broken', or finishes implementing a feature."

Smoke Test

A goal-driven validation pass for the feature you just implemented. The pass ends only when every scenario, both acceptance-criteria-defined and exploratory, passes against a real running instance, every gap or bug found has been fixed, and the working trajectory has been captured as a permanent test.

The word "smoke" is doing real work here: this is not a full regression suite. It is the shortest path that exercises the new behaviour end-to-end against a real running system. If it can't be done in under ten minutes, the scope is wrong, split the feature, not the test.

---

Why this exists

Implementation finishing and the feature working are two different events that teams routinely conflate. Tests pass, types check, lint is clean, and the feature is still broken in production because nobody opened the actual app or hit the actual endpoint. Static checks measure code, not behaviour. This skill closes that gap.

There is a second reason. The model that writes the implementation also writes its own test discipline. Without an external loop that exercises the running system, defects that live between units, exactly the defects integration tests are supposed to catch but rarely do completely, ship straight to review.

---

Step 1: Set the goal explicitly

Before any action, state the goal in one sentence. The goal owns this entire flow; the agent does not exit until the goal is met.

> **Goal:** validate that [feature name / ticket key] works end-to-end against a running instance. Every acceptance criterion passes, every exploratory edge passes, every gap or bug found is fixed before exit, and the successful trajectory is captured as a permanent test.

Surface the goal back to the user in plain prose so they can correct scope before the loop starts.

---

Step 2: Detect the domain

Inspect the staged diff (`git diff --staged --name-only`) and the recent context (intake brief if present, last few commits if not) to pick the domain.

| Signal | Domain | |---|---| | Diff touches `.tsx`/`.jsx`/`.vue`/`.svelte`/`.css`/`.scss`/component dirs, no backend handlers | `ui` | | Diff touches API handlers / controllers / route files / DB migrations / worker code, no frontend files | `backend` | | Diff touches both | `both` | | Ambiguous | ask via `AskUserQuestion` with the three options |

Load the matching reference file(s):

• `ui` → read `references/ui.md`
• `backend` → read `references/backend.md`
• `both` → read both. The priority order interleaves: do P0-P1 of each domain in parallel, then P2 of each, and so on, so a broken backend doesn't block UI validation and vice versa.

Skip the skill entirely when the diff is purely process / config / docs and no user-observable behaviour changed, say so explicitly rather than running an empty loop.

---

Step 3: Derive scenarios from acceptance criteria + diff

This is the part where AI assistance pays off most. Draft the scenario list once, then freeze it as something the loop executes deterministically.

Gather inputs:

• Acceptance criteria, from the intake brief (`## Acceptance Criteria` section), the ticket, the PR description, or directly from the user
• The diff, what the feature actually changed, not just what the ticket asked for (implementations often go beyond or under the spec)
• Skip-conditions, anything the user explicitly deferred ("error handling out of scope for this PR" stays out)

Emit a structured scenario list. Each scenario has:

• An ID (`S1`, `S2`, …)
• A priority tier (P0-P4, domain-specific; see the reference files)
• A one-line behaviour description, phrased as what the user / caller observes
• A pass condition that's objectively verifiable

Show the list to the user via `AskUserQuestion` with options to **Run all (Recommended)** / **Edit scope first** / **Cancel**. Don't start driving the browser or hitting the API before scope is confirmed, a smoke test against a wrong scope is just noise.

---

Step 4: Run the priority loop

Walk the scenarios in priority order, lowest tier first (P0 catches dead-on-arrival, P4 is nice-to-have). The reference files define each tier in detail; this section describes the loop, not the content.

For each scenario:

1. Execute it (drive the browser / hit the endpoint, see reference for tooling). 2. Capture the outcome and the *evidence*: a screenshot, the network log, the response body, the spans emitted, the console output. Evidence is what makes the fix-and-retest loop possible. 3. Record: `pass`, `fail`, or `blocked` (depends on a prior scenario failing).

If P0 fails, stop the cascade, fix P0 first, then restart from P0. P0 is "did the feature even load?", if not, everything else is noise. P1 onwards can collect failures and triage them together.

**No retries on flake.** A scenario that passes on second attempt without an intervening change is a defect, not a config setting. Investigate. Race conditions, hydration timing, and connection-pool warmup all hide behind retries.

---

Step 5: Fix-and-retest

For every `fail`, fix it before exit. Not "log it for later." Not "tracked in the PR description." Fixed.

Loop:

1. Pick the highest-priority failure. 2. Diagnose using the evidenc