speclan-engineering:brainstorm

What this skill does

# SPECLAN Brainstorm Pipeline

Transform a rough thought into SPECLAN artifacts through an interactive loop: ground the thought in the existing project, explore it, decide when to commit, and craft the specs with one quality pass first.

Unlike `/speclan-engineering:hlrd` (a one-shot pipeline over a finished document), this is a **loop**. The user decides when exploration is done and the skill transitions to spec crafting. A typical session produces 1–3 entities.

## Pipeline at a glance

```
Phase 0  → Preflight & Grounding       (understand the thought and its context)
Phase 1  → Exploration Loop            (up to 5 rounds, user-gated)
Phase 2  → Spec Shaping                (enumerate entities, confirm)
Phase 3  → Quality Clarification       (≤1 question per entity, cap 3 total)
Phase 4  → Creation                    (delegate to speclan-format)
Phase 5  → Cross-Referencing           (inline links, enforce no-References-section rule)
Phase 6  → Summary                     (report + offer next actions)
```

## Prerequisites

1. **`speclan` plugin must be loaded.** Verify `speclan-format`, `speclan-id-generator`, and `speclan-query` are available. If missing, stop and tell the user to install the `speclan` plugin.

2. **`speclan/` directory.** Detect it under `$CLAUDE_PROJECT_DIR`. If absent, ask via `AskUserQuestion` whether to create it, point to a different path, or cancel.

3. **File creation delegation.** Every spec file produced by this skill goes through `speclan-format`'s "Creating New Specifications" procedure — never re-derive directory paths or slug rules here. Body templates and merge rules for existing entities live in `${CLAUDE_PLUGIN_ROOT}/../hlrd-authoring/references/entity-content.md` and are shared across both commands.

## Phase 0 — Preflight & Grounding

Brainstorms fail when the skill starts generating ideas before understanding what the user is actually asking about. Grounding is non-optional.

Read `references/grounding.md` now — it contains the classification taxonomy, anchoring procedure, and the interpretation-presentation pattern. The remainder of Phase 0 follows.

### Step 1 — Resolve the thought

- **`$ARGUMENTS` non-empty**: treat as the rough thought. Do not detect file paths — brainstorm inputs are thoughts, not documents. If the argument happens to be a path, treat it as a typo and use the literal text.
- **`$ARGUMENTS` empty**: use `AskUserQuestion` with options `Share a rough idea`, `Explore an existing spec (by ID)`, `Cancel`. On the first two, follow up with a free-text question capturing the idea or the ID.

### Step 2 — Build lightweight context

You need just enough context to ground the thought — not a full project scan:

1. `Read` `speclan/vision.md` and `speclan/mission.md` if they exist. Skip silently if absent.
2. `Glob` `speclan/goals/G-*.md` and Read each file's frontmatter (`id`, `title`, `status`). Skip body content.
3. `Glob` `speclan/features/F-*/F-*.md` (top-level only, no `**`) and Read each frontmatter. Skip nested child features for speed — Phase 0 doesn't need them.

This gives you a map of vision + all goals + top-level features in a handful of reads. Deeper context is loaded on demand during anchoring.

### Step 2.5 — Resolve the owner value

Every spec this pipeline creates or modifies gets its `owner` frontmatter field set to the current git user email, resolved once and cached in pipeline state. Follow the **Owner field resolution** procedure in `../hlrd-authoring/references/entity-content.md` — primary: `git config user.email`, fallback: `git config --global user.email`, finally `AskUserQuestion`. Store the result as `owner_value` and reuse it for every entity created in this session.

Report the resolved owner to the user in the grounding-confirmation message: *"Running brainstorm as owner: `<owner_value>`"* so they know what will be stamped on any specs produced.

### Step 3 — Anchor the thought

Per `references/grounding.md`:

1. Scan the thought for explicit entity IDs: `G-\d{3}`, `F-\d{4}`, `R-\d{4}`, `CR-\d{4}`. If any match, `Glob` to find the file(s) and `Read` them fully — these become the anchor entities.
2. If no explicit ID, extract 2–3 salient nouns from the thought and `Grep` them across `speclan/` with `-l` to find candidate entities. `Read` up to 3 top candidates.
3. If nothing matches, the thought is free-range — proceed without an anchor.

### Step 4 — Classify

Using the thought + anchor + context, classify the intent into exactly one of:

- `new-goal` — strategic outcome, no editable anchor
- `new-feature` — capability, possibly under an existing goal/feature
- `feature-extension` — modifies an existing editable feature
- `new-requirement` — testable obligation under a specific feature
- `requirement-modification` — modifies an existing editable requirement
- `change-request` — any modification to a locked entity (`in-development`, `under-test`, `released`, `deprecated`)
- `not-speclan` — the thought is not specification-shaped (e.g., implementation debugging, general chat)

`references/grounding.md` has decision examples for each class.

### Step 5 — Present the interpretation

Summarize back to the user in 1–3 sentences:

> I read this as **`<classification>`** targeting **`<anchor-or-free-range>`**, in the context of **`<project-summary>`**. Does that match what you have in mind?

Then `AskUserQuestion` with options `Yes, proceed`, `Close — I meant something else`, `Let me rephrase`. On `Let me rephrase`, a free-text follow-up captures the new framing; loop back to Step 3. On `Close`, offer 2–3 alternative classifications via `AskUserQuestion`.

### Step 6 — Handle `not-speclan`

If the thought isn't spec-shaped, don't force it into the pipeline. Say so directly and suggest a better tool:

- Implementation question → answer informally in the conversation, no pipeline.
- Question about existing specs → suggest `/speclan:ask`.
- Finished requirements document → suggest `/speclan-engineering:hlrd`.

Then exit the pipeline cleanly.

## Phase 1 — Exploration Loop

**Goal:** Help the user sharpen the thought until they have enough clarity to commit to specs. The loop runs between 0 and 5 rounds; the user decides when to exit.

### Loop state

Track:
- `round_count` — starts at 0, increments after each round
- `synthesis` — running picture of the evolving idea, updated after each round
- `commitment_gate_answer` — most recent response to the "ready to craft specs?" question

### Per-round procedure

**Step 1 — Divergence (free-form).** Produce 3–4 distinct angles or expansions on the current synthesis. Choose the framing that surfaces genuine ambiguity — don't cite a framework, just ask naturally. Useful framings to pick from (pick what fits the thought, not a formula):

- "What's the minimum viable version?"
- "What's the maximal version?"
- "Who else benefits from this that we haven't named?"
- "What breaks if we don't do this?"
- "What's the first user action when this exists?"
- "What's explicitly out of scope?"
- "What's the hidden assumption we're making?"

Present each angle as a 1-sentence expansion tied to the thought. Present them via `AskUserQuestion` (up to 4 options) so the user can pick one to drill into — and they can always pick "Let me answer in my own words" for a free-text response.

**Step 2 — Drill-down.** Based on the user's pick, ask 1–2 targeted clarifying questions. Mix `AskUserQuestion` (when meaningful choices exist) and plain free-text prompts ("Say more about that — what's the acceptance test for this?"). Keep drill-down tight: two questions max per round.

**Step 3 — Synthesize.** Update the running `synthesis` and show it back to the user as plain text (no question):

> **So far I'm hearing:** *<1–3 sentence summary weaving the original thought and the new drill-down into a sharper statement>*

Don't preface this with "Let me summarize" or similar meta-talk — just state it directly.

**Step 4 — Commitment gate.** `AskUserQuestion`:

> Ready