/mode-selector

name: mode-selector
description: >
  Use this skill when performing deterministic mode selection for session-start. Reads Phase A STATE.md
  recommendations + (future) learnings, sessions, backlog, bootstrap signals
  and returns {mode, rationale, confidence, alternatives}. Pure-function
  contract — no side effects, no STATE.md writes. Phase B scaffold (issue #276);
  full heuristic is follow-up sub-issues.
model: haiku
user-invocable: false
tags: [phase-b, autopilot, mode-selection, scaffold]

Mode-Selector Skill

Status

Heuristic v1 active (issue #291, shipped 2026-04-25). Wired into session-start Phase 7.5 (issue #292, shipped 2026-04-25). Backlog signal source live (issue #293, shipped 2026-04-25): `signals.backlog` is populated by `scripts/lib/backlog-scan.mjs::scanBacklog`. Accuracy feedback loop live (issue #294, shipped 2026-04-25): `scripts/lib/mode-selector-accuracy.mjs::recordAccuracy` writes a `mode-selector-accuracy` learning after the user confirms/overrides the Phase 7.5 banner. Phase B contract is **closed**. Phase C (#277) `/autopilot` Loop Command is the next epic and owns its own PRD.

Purpose

Mode-Selector centralizes the session-mode decision across all consumers: session-start Phase 1.5 banner, `/autopilot` (Phase C), and any future caller that needs a structured recommendation rather than ad-hoc heuristics inline at the call site. Before this skill existed, mode-picking logic was either implicit (user-typed free text) or embedded directly in session-start with no reuse path.

Phase A (`state-md.mjs::parseRecommendations`, issue #272) established the `recommended-mode` frontmatter field written by session-end Phase 3.7a. Phase B is the skill that reads that field (plus future signals) and returns a structured recommendation. The key output is a four-field tuple: `{mode, rationale, confidence, alternatives}`. `mode` is the recommended session type. `rationale` is a ≤120-char human-readable explanation. `confidence` is a float (0.0–1.0) indicating how strongly the selector commits to the recommendation. `alternatives` is an ordered list of `{mode, confidence}` objects representing the next-best choices, enabling callers to offer override options without re-running the selector.

The selector is a pure function: given the same `signals` object it always returns the same output. No file I/O, no network calls, no global state. This makes it trivially testable and safe to call from any skill without side-effect risk.

Contract

Input: `signals` object

• `recommendedMode` (string|null) — Phase A frontmatter field; the `recommended-mode` key from `parseRecommendations()`
• `topPriorities` (number[]|null) — issue numbers from the `top-priorities` frontmatter field
• `carryoverRatio` (number|null) — float 0.0–1.0 from Phase A; fraction of issues carried over from previous session
• `completionRate` (number|null) — float 0.0–1.0 from Phase A; ratio of planned issues completed
• `previousRationale` (string|null) — the `rationale` string written by session-end Phase 3.7a
• `learnings` (object[]|null) — RESERVED; not consumed in scaffold; Phase B-1 heuristic input
• `recentSessions` (object[]|null) — RESERVED; not consumed in scaffold; recent-sessions trend input
• `backlog` (object|null) — `{criticalCount, highCount, staleCount, byLabel, total, vcs, limit}` from `scripts/lib/backlog-scan.mjs::scanBacklog` (Phase B-3, #293). `null` when CLI missing or no git origin — contributes 0 delta.
• `bootstrapLock` (object|null) — RESERVED; not consumed in scaffold; tier-aware sizing hints

Output: `Recommendation` object

| Field | Type | Range / Values | Purpose | |---|---|---|---| | `mode` | string enum | `housekeeping` \| `feature` \| `deep` \| `discovery` \| `evolve` \| `plan-retro` | Recommended session type | | `rationale` | string | ≤120 chars | Human-readable explanation for the recommendation | | `confidence` | float | 0.0–1.0 | Selector commitment; see Fallback Behavior for threshold semantics | | `alternatives` | `{mode, confidence}[]` | 0–3 entries; may be empty, never null | Next-best modes with partial confidence scores |

Invocation Points

Current

• **`skills/session-start/SKILL.md` Phase 7.5** — first wired invocation (issue #292). Renders

`📊 Mode-Selector suggests:` when `confidence < 0.5` (informational, no pre-selection) or `📊 Mode-Selector recommends:` when `confidence >= 0.5` (pre-selects AUQ option 1). Eight graceful no-op conditions documented inline. Note: Phase 1.5 `📋` banner is NOT a Mode-Selector invocation — it reads Phase A STATE.md frontmatter directly via `parseRecommendations`; the Mode-Selector lives at Phase 7.5.

• **`tests/lib/mode-selector.test.mjs`** — 75 tests (7 describe blocks) exercising SPIRAL,

CARRYOVER, high-confidence path, conflicting-signals, stale-signals, alternatives generation, and defensive parsing. `mode-selector.mjs` coverage 100%/100%/100%/100%. Issue #291.

Future

• **`/autopilot` (Phase C, #277)** — auto-execute when `confidence >= 0.85` AND

SPIRAL/FAILED/carryover-50% kill-switches pass. No user prompt in that path.

Companion modules (Phase B closure)

• **`scripts/lib/backlog-scan.mjs::scanBacklog`** — feeds `signals.backlog`. Phase B-3 (#293).

Module-level cache, glab/gh auto-detection, returns `null` on graceful-degradation paths.

• **`scripts/lib/mode-selector-accuracy.mjs::recordAccuracy`** — post-AUQ feedback writer. Phase B-4 (#294).

Subject pattern `<recommended>-selected-vs-<chosen>`; agreement and override land at distinct subjects so the existing learning lifecycle can confirm/contradict them independently.

Scaffold Heuristic (v0)

The v0 scaffold implements a minimal three-branch passthrough. It is intentionally thin so the contract is exercisable by tests before the full Phase B-1 rule-set lands.

selectMode(signals):
  if signals is null/undefined:
    → {mode: 'feature', rationale: 'scaffold: null signals → default', confidence: 0.0, a