Spec Next

# Next-Spec Picker - Auto-Drive Top Priority

Pick highest-priority eligible spec from catalog, hand to `/spec-all`, then loop until no eligible spec remains. Zero-input automation for "just keep working on whatever is most important next."

**Mandate (loop mode).** Keep the machine busy producing *every* piece of work that can be done **without the human**. Bias toward release-blocking tickets first (they rank highest), but the real goal is to exhaust the autonomous backlog: implementation, audits, drift reconciliation, research that resolves from the codebase, and - when a device/emulator is attached - on-device verification of `BlockNeedUserTest` tickets. A ticket that is genuinely blocked on a human (a question, an external resource, a real-device-only check) is *skipped*, not waited on. The loop stops only when nothing remains that the machine can advance alone. Never ask the operator a question mid-loop; defer every human-gated item to the final report.

Two output shapes:
- **Loop / `--once`** - *execution*: advance one spec at a time via `/spec-all`, then (device attached) drain the device-verifiable `BlockNeedUserTest` backlog via `/spec-sweep`.
- **`--plan`** - *planning*: print full ordered release command-sequence covering every open ticket (incl. every `Draft`/`Approved`), ending in release tail. Executes nothing. See [`--plan` mode](#--plan-mode-release-command-sequence).

## Usage

```text
/spec-next                 # loop: pick top-priority eligible, run /spec-all, repeat until none left
/spec-next --once          # pick top, run /spec-all once, stop
/spec-next --dry           # print ranked candidate list and chosen spec, do NOT execute
/spec-next --plan          # print the full ordered release command-sequence (all open tickets), do NOT execute
/spec-next --plan --flavors "<f1,f2>"   # same, threading flavor scope into the /skill-release line
/spec-next --reset-skips   # clear temp/spec-next-skip-cache.json before running

No positional arguments. Selection derived from PLAN/spec-catalog.jsonl plus temp/spec-next-skip-cache.json (auto-pruned, 7-day TTL).

---

Eligibility

Eligible if catalog status is one of:

• Draft
• Approved
• Tactical
• In Progress
• Implemented
• Partial
• Broken
• BlockByOtherTask - conditional: included by preflight, then auto-skipped (reason: blocker-not-verified) unless blocker named in §10 of spec file is currently Verified.

Device-conditional (the autonomous-verification backlog):

• BlockNeedUserTest - not an impl candidate for /spec-all, but is drainable autonomous work when a device/emulator is attached. The impl loop ignores these; the post-impl Stage 5.5 device drain routes the whole BlockNeedUserTest backlog to /spec-sweep, which runs each ticket's device test and flips it to Verified/Partial/Broken. With no device attached they stay parked (listed under "Waiting on human" in the final report). Tickets whose statusNote says a real device is required (not an emulator) are attempted by /spec-sweep, which reports them back as still-blocked when the emulator cannot satisfy the check - those remain human-gated.

Excluded (always):

• Verified, Archived - terminal
• BlockQuestions, BlockExternal - waiting on human / external resource
• Any unknown / malformed status - skip and continue down ranked list

---

Process

Stage 0 - Device probe (once per session)

Before the loop, detect whether on-device verification is available this run:

pwsh -NoProfile -File scripts/devtest/device-ready.ps1 -Package com.sza.fastmediasorter.debug -CheckMcp -Json

• Exit 0 (ready:true) -> DEVICE_ONLINE = true. Record the selectedDevice id. The session will run Stage 5.5 (device drain) after the impl loop exhausts.
• Any other exit -> DEVICE_ONLINE = false. The BlockNeedUserTest backlog stays parked for the human; Stage 5.5 is a silent no-op.

This is a single read-only probe; never blocks the loop. Re-probe is unnecessary - a device attached at session start is assumed available for Stage 5.5.

Stage 1 - Preflight (rank + skip-cache + auto-skip + drift, one call)

pwsh -NoProfile -File scripts/spec_catalog/spec-next-preflight.ps1 -Exclude <processed-ids-csv>

One read-only call replaces previous search.ps1 + manual rank + skip-cache.ps1 -Action list + per-candidate preview.ps1 + drift-check.ps1 chain. Returns single JSON blob:

• ranked[] - eligible set (statuses above), already sorted priority desc -> updated desc -> id asc, with active persistent skip-cache and -Exclude round-memory set already removed.
• skip_cache / skip_cached_ids - active persistent skips and which ranked ids they removed (informational; no action needed).
• auto_skipped[] - candidates preflight previewed and rejected while walking down to selection. Each { id, reason, detail }, reason ∈ { tier-5-epic | owner-gate | blocker-not-verified | research-heavy }.
• selected - chosen ticket's full preview.ps1 payload (status, frontmatter, sections, tactical_folder, last_audit_present, timber_tags_kt, depends_on) plus drift (drift-check.ps1 verdict object) and status_mismatch ({catalog,file} or null). null when eligible set exhausted.

-Exclude carries in-memory processed round-memory set (Stage 5) so each loop iteration gets next candidate in one call. First iteration: omit -Exclude.

selected == null -> eligible set exhausted -> final report (Stage 6) and stop.

Stage 2 - Persist preflight side effects (only mutations in selection)

Preflight is read-only by contract; this skill performs writes it implies:

1. Persist auto-skips. For each entry in auto_skipped[], write to persistent cache and log one line [auto-skip] <id> - <reason>:

   pwsh -NoProfile -File scripts/spec_catalog/skip-cache.ps1 -Action add -Id <id> -Reason "<reason>"
   

   Th