/smoke — scaffold the manual smoke-test checklist

You are scaffolding phase 7 of the workflow in CLAUDE.md → "Issue → PR Workflow" — the acceptance gate before merge, alongside the adversarial phase (/adversarial-review). A smoke doc is a checklist verified against a running dev stack, and the human's confirmation is the point of the gate. Automatable steps can be walked by the agent in a real browser via /smoke-walk (Playwright MCP, reusing the @portalai/e2e fixture), which produces a per-step evidence report the human reviews; manual-only steps (third-party redirects, payments, visual judgment, real vendor accounts) the human walks. It is never a jest suite, and you never check a box or merge — the agent produces evidence, the human confirms. The PR merges only after CI is green and the human has confirmed each required review-chain phase (CLAUDE.md → "The merge gate"), smoke among them.

Arguments

Invoked as /smoke [issue-number]. The number is optional — derive it from the spec (or condensed doc) on the current branch. If you can't resolve exactly one, ask once and stop.

Steps

1. Check prerequisites on the current branch

git branch --show-current            # must be the feature branch, NOT main
ls docs/*.spec.md docs/*.condensed.md   # find the spec or condensed doc
git log --oneline main..HEAD         # implementation commits must exist

• Implementation must be present. If the branch has only docs commits, stop — the smoke doc verifies built behavior; scaffolding it early produces fiction. Tell the user to finish the plan's slices first.
• A spec (or condensed doc) must be present. No spec → stop with the right next command (/spec <N>, or /discovery <N> condensed for small tickets).
• Condensed branch? If the branch carries docs/<SLUG>.condensed.md, do not create a .smoke.md — append or refresh that doc's ## Smoke (manual, against your dev stack) section using the same rules below, and skip to the hand-off.

2. Collect the three inputs

1. The spec's Acceptance criteria — the contract. Coverage rule: every acceptance criterion maps to at least one walkthrough step. This is the assertion the doc is built around.
2. The plan's slices — the natural grouping for the § sections.
3. The branch diff (git diff main...HEAD --stat) — a sweep for user-visible surfaces the spec under-specified (a new dialog, a changed helper text, a new CLI flag). Anything user-facing in the diff that no criterion covers gets its own step.
4. Automatability of each step — decide whether the agent can drive it in a browser (navigate/click/read a rendered value) or it needs a human (third-party redirect, payment flow, visual/aesthetic judgment, real vendor account, email/SMS round-trip). Tag the human-only ones — manual; the rest are /smoke-walk-eligible. This tag is what /smoke-walk reads to know which steps to attempt vs. report could-not-automate.

3. Read one reference smoke doc

Default to .claude/skills/smoke/EXAMPLE.smoke.md — preflight + sectioned walkthrough + sign-off + bug template, with sections independent after preflight. The exemplar lives beside this skill because phase docs in docs/ are ephemeral — swept by the next feature ticket — so it can't be kept there.

4. Write docs/<SLUG>.smoke.md

# <slug> — Smoke Suite

Manual smoke test for [#<N>](…) — <one line: what shipped>. **Branch under test:** `<branch>` (PR [#<P>](…)).

## Preflight

### Environment

- [ ] `git checkout <branch> && git pull --ff-only`
- [ ] `npm install` <+ build/migrate steps ONLY if this branch needs them — name the migration; omit and say "no migration" when there is none>
- [ ] `npm run dev` boots cleanly (API :3001, web :3000) <adapt to what the ticket touches>

### Fixtures

- [ ] <the data/org/station the walkthrough assumes, and how to get it>

### Reset between runs

- [ ] <how to re-run cleanly; "no reset needed — read-only" when true>

## §1 — <feature area, usually plan slice 1>

- [ ] <action: the exact prompt / click / command>
- [ ] <expected: the externally-observable result. Where DB state is the truth, name the `db:studio` table + column to inspect>

## §2 — <…>

## §<n> — Error & edge cases

- [ ] <the failure modes the spec's Risks name>

## Sign-off

- [ ] Every section above verified
- [ ] <date + name> — confirmed against my own running stack

## Bug-filing template

Section: · Expected: · Got: · Repro: · Identifiers (org/job/entity ids):

Hard rules:

• Verified against a running stack; automatable steps agent-walkable. The doc targets a real dev stack (npm run dev, the Auth0 tenant, the DB). Steps a browser can drive are walked by the agent via /smoke-walk for evidence; steps that need a human are tagged — manual. Either way it is not a jest suite — no "run this test file".
• Every box scaffolds unchecked, and you never check one — not the agent, not /smoke-walk. The agent produces an evidence report; checking boxes is the human's act of confirmation, and a pre-checked box — or a verified the agent didn't truly observe — forges the gate.
• Coverage is complete: every spec acceptance criterion → ≥ 1 step; every user-visible diff surface → ≥ 1 step. If a criterion can't be verified in a browser at all, tag it — manual (or say so in the doc) rather than dropping it silently.
• Steps are concrete: exact prompts in quotes, exact commands, exact expected values or shapes — "works correctly" is not an expected result.
• No commit, no push — the user reviews the checklist, walks it, checks boxes, and confirms.

5. Hand off to the user

Stop. Report: the doc and its section/step counts, the acceptance-criteria → section mapping (so coverage is auditable at a glance), and the gate statement — the PR merges after CI is green and they've confirmed the walkthrough.

What this skill is not

• It is not /verify or a test runner — /smoke scaffolds the checklist; /smoke-walk is the executor that drives the app in a browser for evidence. Neither runs jest/Playwright specs.
• It is not the place to fix what the walkthrough will find — bugs found during the walk go through the doc's bug-filing template.
• It does not merge the PR, check CI, or confirm anything on the user's behalf.