spec

What this skill does

# Spec

This phase is **thinking, not building**. No code until the user approves the design. On approval, the chain advances to `scope` → `dispatch`. The user picks the advancement mode at Step 0.

This skill drives **Layer 0.5 (Task Triage)** and **Layer 4 (Brainstorming/Spec)** from the doctrine. Multi-level review (L1–L5) runs later during `/hyperflow:dispatch` per the triage's chosen flow profile.

## Iron Rules

- **Failure recovery (rule 14).** Worker errors, malformed output, NEEDS_REVISION verdicts, and Reviewer errors across every dispatched agent (Classifier, Triage Reviewer, Searchers, Writers, Analyst, batched Reviewer) follow the canonical policy in [`skills/hyperflow/failure-recovery.md`](../hyperflow/failure-recovery.md). Retry → escalate → abort. Chain budget: 3 cumulative aborts.

## Per-Step Agent Map (DOCTRINE rule 12)

Every substantive step dispatches at least one Agent per DOCTRINE rule 12. Trivial steps per §12.1 may be performed inline by the orchestrator.

| Step | Sub-phase | Worker tier | Thinking tier | Notes |
|---|---|---|---|---|
| 0 — Chain mode | — (atomic) | — | — | `AskUserQuestion` only (exempt) |
| 0.5 — Operational choices | — (atomic) | — | — | `AskUserQuestion` only (exempt) |
| 1 — Triage | — (atomic) | — | **Classifier** (Opus) · **Triage Reviewer** (Sonnet) | Atomic per §12.2.8: single Worker → Reviewer pair, no independent angles. Reviewer verdicts: `PASS` / `RECLASSIFY` / `ESCALATE` (DOCTRINE rule 15). Skips on P4 conditions; see body |
| 2 — Context Exploration | 2a + 2b (P1 parallel) | Searcher ×2 per sub-phase [P3 concurrent with Step 1] | **Reviewer** (Sonnet) per sub-phase | P3: Steps 1+2 dispatched in same message; no coverage Reviewer at Step level (D4) |
| | 2a — Codebase surface mapping | Searcher ×2 (glob discovery + dependency graph) | **Reviewer** (Sonnet) | Parallel with 2b |
| | 2b — Convention and test pattern scan | Searcher ×2 (test pattern probe + lint/config scan) | **Reviewer** (Sonnet) | Parallel with 2a |
| 3 — Multi-dim analysis | 3a + 3b + 3c (P1 parallel) | Writer ×1–2 per sub-phase | **Reviewer** (Sonnet) per sub-phase + **Analyst** (Opus) final synthesis | P4-skippable; `--thorough` always runs |
| | 3a — Intent and technical-fit analysis | Writer ×2 (user-intent angle + technical-fit angle) | **Reviewer** (Sonnet) | Parallel with 3b and 3c |
| | 3b — Scope, constraints, and risks analysis | Writer ×2 (scope/constraints angle + risks angle) | **Reviewer** (Sonnet) | Parallel with 3a and 3c |
| | 3c — Alternatives synthesis | Writer ×1 (single canonical aggregation — no parallel angle) | **Reviewer** (Sonnet) | Parallel with 3a and 3b; single-Worker justified: one alternatives set |
| | 3d — Analyst synthesis | — | **Analyst** (Opus) consolidating 3a + 3b + 3c into unified 6-dim brief | Sequential — depends on 3a + 3b + 3c all PASS |
| 4 — Smart questions | — (atomic) | — | — | `AskUserQuestion` only (exempt) · floor: 2 always · pre-flight checks `.hyperflow/memory/project-decisions.md` to skip already-answered questions |
| 5 — Requirement Synthesis | — (atomic) | Writer (Sonnet) | **Reviewer** (Sonnet · batched with Step 6) | Atomic: single canonical one-paragraph restatement; no independent angles |
| 6 — Approach proposals | 6a + 6b (sequential; P3 concurrent with Step 5) | Writer ×2 per sub-phase | **Reviewer** (Sonnet · batched over both Steps 5+6) | P4-skippable; 6b depends on 6a |
| | 6a — Approach candidate drafting | Writer ×2 (lightweight-approach angle + heavyweight-approach angle) | **Reviewer** (Sonnet) | Parallel with Step 5; sequential before 6b |
| | 6b — Trade-off and fit evaluation | Writer ×2 (fit-analysis angle + risk-analysis angle) | **Reviewer** (Sonnet) | Sequential after 6a; depends on 6a candidates as input |
| 7 — Design sections | 7a + 7b + 7c (P1 parallel) | Writer ×1–2 per sub-phase [P1] | **Reviewer** (Sonnet · per-batch) batched over sub-phase aggregate [P2] | One combined user gate after full batch review |
| | 7a — Structural sections (Architecture + Data flow) | Writer ×2 (Architecture Writer + Data flow Writer) | **Reviewer** (Sonnet) | Parallel with 7b and 7c |
| | 7b — Decision sections (Key decisions + Edge cases) | Writer ×2 (Key decisions Writer + Edge cases Writer) | **Reviewer** (Sonnet) | Parallel with 7a and 7c |
| | 7c — File structure section | Writer ×1 (single canonical section — no parallel angle) | **Reviewer** (Sonnet) | Parallel with 7a and 7b; single-Worker justified |
| 8 — Spec finalize | — (atomic) | Writer (Sonnet) | **Reviewer** (Opus · final-pass tier) | Atomic: single canonical finalization; no independent angles |
| 9 — Hand off | — (atomic) | — | — | Skill tool invocation — trivial inline per §12.1 (one tool call, no generation, no review) |

Substantive steps = 1, 2, 3, 5, 6, 7, 8. Each appears in the usage summary.
Steps decomposed into sub-phases (12.2): 2 (→ 2a, 2b), 3 (→ 3a, 3b, 3c), 6 (→ 6a, 6b), 7 (→ 7a, 7b, 7c).
Atomic-exempt steps (12.2.8): 0, 0.5, 4, 9 (AskUserQuestion / single Skill call); 1 (single Classifier, no angles); 5 (single canonical synthesis); 8 (single canonical finalization).

## Approval Gates

| Gate | When | Format |
|---|---|---|
| Chain mode | Step 0, once per chain | `AskUserQuestion` — auto / manual |
| Design section approval | Step 7, one combined gate after batched review | `AskUserQuestion` — approve / revise per section |
| Phase advance (if `manual` mode) | Step 9, before invoking `scope` | `AskUserQuestion` — continue / stop |

## Flow

### Step 0 — Choose chain mode (FIRST tool call · STRUCTURAL GATE)

This is a **structural gate** per DOCTRINE rule 8. It MUST fire every time the skill is invoked directly. "No clarifying questions" / "auto-pilot" / "always-on" / any other autonomy directive does NOT skip it. The agent MUST `AskUserQuestion` here — defaulting to `auto` without asking is a doctrine violation.

If invoked with a `chain-mode=<auto|manual>` arg (from a prior skill in the chain), skip this step — the previous chain-starter already asked.

Otherwise, **before any research, triage, or analysis**, ask via `AskUserQuestion`. Per DOCTRINE rule 8, the recommended option goes first with `(Recommended)`:

```
How should I advance through the chain after each phase?

  Auto (Recommended)  — chain forward through spec → scope → dispatch with no gates.
                        Fewer interruptions, faster end-to-end.

  Manual              — pause between phases and ask before advancing.
                        More control, more confirmations.
```

`Auto` is the recommended default because most users invoking a chain-starter want momentum; `Manual` exists for high-risk or exploratory work. Wait for the user's answer. Do not proceed without it. Save the chosen mode and propagate via `args: "chain-mode=<mode>"`.

If the agent cannot present `AskUserQuestion` as a popup, use the Codex fallback: print the same gate as a `Hyperflow Question` chat block with numbered options, then stop and wait for the user's answer. If no interactive channel is available at all, print an error and stop — never silently default.

### Step 0.5 — Operational Choices (auto-mode only · STRUCTURAL GATE · fires immediately after Step 0)

When the user picks `Auto` at Step 0 AND operational args (`commit=`, `branch=`, `push=`) were NOT already propagated, fire ONE `AskUserQuestion` call with 3 questions covering every operational decision the chain needs. After this batch, the chain runs silently until the end-of-chain audit + deploy gates — user is interrupted exactly twice at startup (chain-mode in Step 0, ops in Step 0.5), never again until done.

Skip when `chain-mode=manual` (per-phase pauses cover ops decisions) OR when operational args are already propagated (re-asking is an invented-gate violation).

The 3-question batch is identical to scope Step 0.5 — see [scope/SKILL.md § Step 0.5](../scope/SKILL.md#step-05--operational-choices-auto-mode-only--structural-gate--fires-immediately-after-step-0) for