speclan-engineering:brainstorm-plus

What this skill does

# SPECLAN Brainstorm Plus Pipeline

Multi-agent brainstorming that produces sharper specs by dispatching 3–5 parallel subagents — each applying a distinct ideation technique — then synthesizing the cross-technique output into strong threads for interactive progression.

## How this differs from `/brainstorm`

| Phase | `/brainstorm` | `/brainstorm-plus` |
|-------|---------------|--------------------|
| Grounding | Main skill | **Same** (references brainstorm's procedure) |
| Divergence | Main skill produces 3–4 angles per round | **3–5 parallel subagents**, each one technique, one shot |
| Synthesis | Inline in the conversation loop | **Explicit Phase 3** with cross-technique clustering |
| Progression loop | Up to 5 rounds | Up to **3 rounds** (subagents already did the heavy lifting) |
| Spec shaping / quality / creation | Main skill | **Same** (references brainstorm's procedure) |

The delta is phases 0.5–3. Everything else is shared.

## Pipeline at a glance

```
Phase 0  → Grounding                (REUSE brainstorm Phase 0)
Phase 1  → Technique Selection      (NEW — parse flags OR auto-pick 3–5 techniques)
Phase 2  → Parallel Agent Dispatch  (NEW — spawn subagents in one turn)
Phase 3  → Synthesis & Thread Pick  (NEW — cluster, present 2–3 threads, user picks)
Phase 4  → Interactive Progression  (REUSE brainstorm Phase 1, cap 3 rounds)
Phase 5  → Spec Shaping             (REUSE brainstorm Phase 2)
Phase 6  → Quality Clarification    (REUSE brainstorm Phase 3)
Phase 7  → Creation                 (REUSE brainstorm Phase 4)
Phase 8  → Cross-Referencing        (REUSE brainstorm Phase 5)
Phase 9  → Summary                  (REUSE brainstorm Phase 6 + technique contributions)
```

## Prerequisites

1. **`speclan` plugin loaded** — `speclan-format`, `speclan-id-generator`, `speclan-query`. Same as `/brainstorm`.
2. **`Agent` tool available** — if the harness doesn't expose parallel subagent dispatch, fall back to recommending `/speclan-engineering:brainstorm` and stop.
3. **`speclan/` directory exists or will be created** — same handling as `/brainstorm`.
4. **File creation delegation** — every spec goes through `speclan-format`'s "Creating New Specifications" procedure. Shared body templates live in `${CLAUDE_PLUGIN_ROOT}/../hlrd-authoring/references/entity-content.md`.

## Phase 0 — Grounding

**Delegate to `/brainstorm` skill's Phase 0.** Load `${CLAUDE_PLUGIN_ROOT}/../brainstorm/SKILL.md` and `${CLAUDE_PLUGIN_ROOT}/../brainstorm/references/grounding.md`. Follow the procedure exactly: resolve the thought, detect speclan directory, build lightweight context, **resolve the `owner_value` from `git config user.email` and cache it** (brainstorm Phase 0 Step 2.5), anchor via explicit IDs or noun Grep, classify into one of the seven types, present the interpretation, handle `not-speclan` exit.

**One difference at argument resolution**: before treating `$ARGUMENTS` as the thought, strip the `--techniques=<csv>` flag if present. See Phase 1 Step 1 for flag parsing — it runs before grounding Step 1 so the thought passed to grounding is the pure text.

State captured from Phase 0 for downstream phases:

- `thought` — the cleaned rough idea
- `classification` — one of the seven classes from `grounding.md`
- `anchor` — the anchor entity details or `null`
- `project_summary` — 1-sentence description of the project's vision/mission
- `owner_value` — the resolved git user email used as the `owner` field on every spec this pipeline creates or modifies

If classification is `not-speclan`, exit the pipeline (same as `/brainstorm`).

## Phase 1 — Technique Selection

**Goal:** Decide which 3–5 brainstorming techniques to dispatch as parallel subagents.

### Step 1 — Parse the flag (if present)

Before handing the thought to Phase 0, scan `$ARGUMENTS` for `--techniques=<csv>`:

- **Pattern**: `--techniques=<comma-separated-names>` at the start, end, or middle of `$ARGUMENTS`.
- **Valid names**: `scamper`, `crazy-8s`, `reverse`, `constraint`, `first-principles`, `analogy`, `six-hats`, `random-input`. See `references/techniques.md` for the canonical list.
- **Strip the flag** from `$ARGUMENTS` before passing the remaining text as the thought.
- **Validate** each name. If any is invalid (typo, unknown), use `AskUserQuestion` to show the valid list and ask the user to fix. Don't silently drop invalid names.
- **Count check**: the user may specify 1–8 techniques. If they specify more than 5, warn via `AskUserQuestion` that synthesis works best with ≤5 and let them confirm or trim.

If the flag was present and valid, skip to Step 3 (user-picked, no auto-selection).

### Step 2 — Auto-selection (no flag)

Read `references/technique-selection.md` now — it contains the decision matrix that maps `(classification, anchor, thought_shape)` to 3–5 techniques.

Apply the matrix:

1. **Mandatory techniques** per classification (e.g., SCAMPER is mandatory for `feature-extension`).
2. **Skip rules** based on preconditions (e.g., SCAMPER requires an anchor; skip if `anchor == null`).
3. **Boost rules** based on thought shape (e.g., include `six-hats` when the thought is multi-stakeholder, `random-input` when the thought is vague/short, `analogy` when the thought has a clear domain).
4. **Cap at 5** — never dispatch more than 5 subagents in one session. If more techniques qualify, drop the lowest-priority ones per the matrix's tie-breaker.

Record the selection as `selected_techniques: [<name>, ...]` with a 1-line reason per technique.

### Step 3 — Present for confirmation

Show the user the selected techniques in plain text:

> **For this brainstorm I'm dispatching these techniques in parallel:**
>
> 1. **SCAMPER** — the thought targets an existing feature, so mutation lenses apply
> 2. **Reverse Brainstorming** — the thought touches risk/security
> 3. **Constraint-Based** — stress-testing surfaces constraints you may not have considered
> 4. **First Principles** — the thought has buried assumptions worth exposing
>
> Spawning 4 parallel subagents. This will take longer than a regular brainstorm but produces a richer starting point.

Then `AskUserQuestion`:

> Dispatch these techniques?

Options:

1. `Dispatch as planned` → advance to Phase 2
2. `Adjust selection — let me pick` → drop into a sub-loop: show the 8 canonical techniques via `AskUserQuestion` (may need pagination since `AskUserQuestion` supports ≤4 options per question — split into two pages of 4), let the user toggle selections, then confirm the final list
3. `Cancel` → exit the pipeline

## Phase 2 — Parallel Agent Dispatch

**Goal:** Spawn one `general-purpose` subagent per selected technique, **in a single turn** for true parallelism.

### Step 1 — Build prompts

For each technique in `selected_techniques`, read its agent prompt template from `references/techniques.md` and fill in the placeholders:

- `{THOUGHT}` — the cleaned thought from Phase 0
- `{CLASSIFICATION}` — the grounding classification
- `{ANCHOR}` — the anchor entity details, or "free-range (no anchor)"
- `{PROJECT_SUMMARY}` — the 1-sentence project summary

Each prompt is self-contained — subagents start fresh with no conversation context, so the prompt must carry every fact the subagent needs.

### Step 2 — Dispatch in one turn

**CRITICAL**: spawn all subagents in a **single message** with multiple `Agent` tool calls. Do not spawn them sequentially — parallel dispatch is the whole point of this skill.

Each call uses:
- `subagent_type: "general-purpose"`
- `description`: "<technique-name> brainstorm"
- `prompt`: the filled prompt template

### Step 3 — Collect outputs

Each subagent returns a markdown document. Tag the output with its technique name and store under `agent_outputs[<technique>] = <markdown>`.

Agents are instructed to follow a conventional structure (per-idea headers, commentary section), but they may drift. Phase 3's parsing is robust to reasonable variation.

### Step 4 — Handle failures

- **Empty or clearly off-task output** (subag