scope

What this skill does

# Scope

Decompose, don't build. Read-only with respect to source code. The only writes are to `.hyperflow/tasks/`, `.hyperflow/memory/`, and `.hyperflow/specs/`. When the task file is ready, hand off to `dispatch` (auto or with a gate, depending on chain mode).

This skill exercises **Layer 0 (Project Analysis)** for context, **Layer 6 (Project Memory)** for past-learning surfacing, and **Layer 7 (Task Templates)** for decomposition patterns. It also inherits the triage classification from `/hyperflow:spec` to size each batch correctly.

## Iron Rules

- **Failure recovery (rule 14).** Worker errors, malformed output, NEEDS_REVISION, and Reviewer errors 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 + 12.2)

Every substantive step dispatches at least one Agent per DOCTRINE rule 12. Trivial steps per §12.1 may be performed inline by the orchestrator. Non-trivial Steps decompose into ≥ 2 named sub-phases per DOCTRINE rule 12.2.

| Step | Sub-phase | Worker tier | Thinking tier | Notes |
|---|---|---|---|---|
| 0 — Chain mode | — (atomic) | — | — | `AskUserQuestion` only; 12.2.8-exempt |
| 0.4 — Triage (Classifier + Reviewer) | — (atomic) | Classifier (Sonnet) [if not inherited] | **Triage Reviewer** (Sonnet) [if not inherited + P4 conditions not met] | Skipped entirely when chained from spec (spec's validated triage is canonical); on direct invocation, dispatches its own Classifier then Triage Reviewer; skips Triage Reviewer on P4 conditions; 12.2.8-exempt |
| 0.5 — Ops choices | — (atomic) | — | — | Single `AskUserQuestion` batch; 12.2.8-exempt |
| 1 — Route | — (atomic) | — | — | Single mechanical routing decision; 12.2.8-exempt |
| 2 — Research | 2a + 2b + 2c (P1 parallel) | | | Sub-phase aggregate handed to Step 3 |
| | 2a — Surface mapping | Searcher × 2 (glob discovery + import-graph traversal) | **Reviewer** (Sonnet) | P1; no inter-dependency with 2b/2c |
| | 2b — Semantic indexing | Searcher × 2 (type-system probe + symbol-graph probe) | **Reviewer** (Sonnet) | P1; no inter-dependency with 2a/2c |
| | 2c — Convention scan | Searcher × 1 (test patterns + lint config; single-angle justified: no independent probe angle for config) | **Reviewer** (Sonnet) | P1; single Worker per 12.2.3 exception |
| 2.5 — Clarify | — (atomic) | — | — | At most one `AskUserQuestion`; 12.2.8-exempt |
| 2.6 — Vestigial | — | — | — | Does nothing; number reserved for back-compat |
| 3 — Decompose | 3a + 3b + 3c | | | 3a fires first; 3b/3c parallel after 3a |
| | 3a — Batch graph | — | **Planner** × 1 (Opus; dependency analysis + parallel/sequential mapping; single-angle: canonical aggregation, no independent angle) + **Reviewer** (Sonnet · per-sub-phase: completeness + sane batch boundaries; verdict ∈ {PASS, NEEDS_REVISION, ESCALATE}) | Sequential synthesis; Planner justified single-Worker per 12.2.3; Reviewer required per 12.2.4 |
| | 3b — Complexity sizing | Searcher × 2 (sub-task LOC estimation + subsystem cross-cut check) | **Reviewer** (Sonnet) | Parallel; depends on 3a output |
| | 3c — Acceptance criteria | Writer × 2 (per-sub-task criteria + verification hooks) | **Reviewer** (Sonnet) | Parallel; depends on 3a output; 3b and 3c concurrent |
| 4 — Write task file | 4a + 4b + 4c (P3 concurrent with Step 6) | | | 4a fires first; 4b/4c parallel after 4a |
| | 4a — Status + Goal + Why | Writer × 2 (status block draft + goal/why narrative) | **Reviewer** (Sonnet) | Sequential first sub-phase; anchors 4b/4c |
| | 4b — Scope + Affected files | Writer × 2 (scope-at-a-glance table + affected-file listing) | **Reviewer** (Sonnet) | Parallel; depends on 4a output; runs concurrently with 4c |
| | 4c — Execution plan + Batches + Verification | Writer × 2 (execution plan ASCII + batch checklist) | **Reviewer** (Sonnet) | Parallel; depends on 4a output; runs concurrently with 4b |
| | 4d — Final task-file verification | — | **Reviewer** (Sonnet · per-step) verifies whole task file vs design | Fires after all sub-phases complete; ensures every design requirement maps to ≥1 sub-task and no orphan sub-tasks exist |
| 4+6 — parallel | — | Writer (Step 4) ∥ Writer (Step 6) fire after Step 3 (P3) | — | Concurrent dispatch; both wait on Step 3 aggregate |
| 5 — Output | — (atomic) | — | — | Print only; §12.1-exempt |
| 6 — Memory | — (atomic; single-angle) | Writer (Sonnet) appends to memory files | **Reviewer** (Sonnet) checks duplicates/contradictions | Single Worker → Reviewer with no independent angles; 12.2.8-exempt |
| 7 — Hand off | — (atomic) | — | — | `Skill` tool invocation; §12.1-exempt |

**Latency flags:** `--thorough` disables P1 **in Step 4 only** (sequential Writer-internal section drafts instead of parallel). Step 2 sub-phases (also P1) are NOT affected — they stay parallel under all flag configurations because they are independent reads with no quality tradeoff. P3 (Steps 4 + 6 concurrent) is always on. See [`../spec/references/latency-patterns.md`](../spec/references/latency-patterns.md) for pattern definitions.

## Approval Gates

| Gate | When | Format |
|---|---|---|
| Chain mode | Step 0, only if invoked directly | `AskUserQuestion` — auto / manual |
| Decomposition sanity | Step 4, after writing the task file | Print the batch summary; user reads it |
| Phase advance (if `manual` mode) | Step 7, before invoking `dispatch` | `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. Defaulting to `auto` without asking is a doctrine violation.

**Latency arg:** `--thorough` (or `depth=max`) disables P1 **in Step 4 only** (sequential Writer-internal section drafts instead of parallel). The Step 2 parallel Searchers are NOT affected — they stay parallel under all flag configurations because they are independent reads with no quality tradeoff. P3 (Step 4 + Step 6 concurrent dispatch) stays on always. If the user passes `--thorough`, note it and apply to Step 4 dispatch only.

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

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

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

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

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

Wait for the user's answer. Do not proceed without it. Save the chosen mode and propagate via `args: "chain-mode=<mode>"` when invoking dispatch.

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.4 — Triage (Classifier + Reviewer) (DOCTRINE rule 15 · atomic-exempt)

Atomic-exempt: no parallel probe dimension exists. Two distinct paths depending on whether scope is chained from spec or invoked directly.

**Path A — chained from `/hyperflow:spec`:** spec already ran its own Classifier and Triage Reviewer and passed the validated triage JSON via chain args. Scope skips this step entirely — re-classifying a triage that spec already vetted is redundant and wasteful. Print:

```
Triage Reviewer skipped — spec's validated triage inherited via chain args.
```

Then proceed to Step 0.5.

**Path B — invok