ideation

What this skill does

<what-to-do>

# Ideation

Transform unstructured brain dumps into implementation artifacts through a conversational interview that builds shared understanding before writing anything. HTML is used for interactive decision-making (visualizations, comparisons, Mission Brief contract); Markdown is used for reference documents (specs, PRDs).

## Workflow

```
INTAKE → INTERVIEW LOOP → CONTRACT.HTML → PHASING → SPEC.MD GENERATION → HANDOFF
              ↓                  ↓             ↓             ↓                ↓
         Accept the mess    One question    Mission       Repeatable?      Phase track
                            at a time,      Brief with      ↓              + copy buttons
                            explore code    confidence   Template +        in contract
                            + show HTML     + scope      per-phase
                            examples        tiers        deltas
```

## Phases 1-2: Interview

Read and follow `${CLAUDE_PLUGIN_ROOT}/references/interview-engine.md` for the complete intake and interview loop process. Execute all phases described there before proceeding to Phase 3.

Read `${CLAUDE_PLUGIN_ROOT}/references/confidence-rubric.md` for the detailed scoring criteria.

## Phase 3: Contract (HTML)

When confidence ≥ 95%, generate the Mission Brief contract as an HTML document. **Not before.**

1. Use `AskUserQuestion` to confirm project name if not obvious from context
2. Convert to kebab-case for directory name (this becomes the `slug`)
3. Create output directory `./docs/ideation/{slug}/`
4. **Write `contract-data.json`** in the output directory. This is a JSON file conforming to the `ContractData` schema — the CLI generates the HTML from it. The JSON captures all interview findings:

   ```json
   {
     "projectName": "Human-Readable Name",
     "slug": "kebab-case-name",
     "date": "YYYY-MM-DD",
     "status": "Draft",
     "supersedes": null,
     "confidence": {
       "score": 96,
       "dimensions": [
         { "key": "scope", "score": 100, "label": "Scope", "reason": "One sentence explaining the score" },
         { "key": "risk", "score": 92, "label": "Risk", "reason": "One sentence" },
         { "key": "effort", "score": 95, "label": "Effort", "reason": "One sentence" },
         { "key": "clarity", "score": 98, "label": "Clarity", "reason": "One sentence" },
         { "key": "tests", "score": 95, "label": "Tests", "reason": "One sentence" }
       ]
     },
     "problem": ["paragraph 1", "paragraph 2"],
     "goals": ["Measurable goal 1", "Measurable goal 2"],
     "successCriteria": ["Pass/fail criterion 1", "Pass/fail criterion 2"],
     "scope": {
       "mvp": [{"item": "Core feature", "reason": "Why it's MVP"}],
       "full": [{"item": "Full feature", "reason": "Optional rationale"}],
       "stretch": [{"item": "Stretch feature"}],
       "outOfScope": [{"item": "Excluded item", "reason": "Why excluded"}],
       "future": ["Deferred idea 1"]
     },
     "execution": {
       "strategy": "Sequential",
       "phases": [
         {
           "title": "Phase name",
           "risk": "low",
           "blocking": true,
           "specPath": "docs/ideation/slug/spec-phase-1.md",
           "notes": "Brief description of what this phase covers"
         }
       ],
       "agentTeamPrompt": "only if 2+ phases parallelizable"
     }
   }
   ```

   **Confidence dimensions:** Each dimension gets a numeric score (0-100) and a one-sentence reason. The overall `score` is what the hero displays; dimensions show the breakdown.

   **Phase fields:** `risk` (high/medium/low), `blocking` (boolean), `specPath` (path to spec), `notes` (brief description). Optional: `kind` ("gate" for human checkpoints), `prereqs` (array of phase titles this depends on).

5. **Run the contract generator**:
   ```bash
   npx tsx ${CLAUDE_PLUGIN_ROOT}/scripts/contract-gen.ts \
     --input ./docs/ideation/{slug}/contract-data.json \
     --output ./docs/ideation/{slug}/contract.html
   ```
   The CLI handles lineage automatically — if `contract.html` already exists, it renames it to `contract-{date}.html` and sets the supersedes link.

6. Open in browser: run `open ./docs/ideation/{slug}/contract.html` (macOS) or `xdg-open` (Linux)
7. Use `AskUserQuestion` to get approval — include the scope tier question:

```
Question: "Does this contract capture your intent? Which scope tier should we target?"
Options:
- "Approved — Full scope (Recommended)" - Build MVP + Full tiers
- "Approved — MVP scope" - Ship the minimum viable version first
- "Approved — Stretch scope" - Include MVP + Full + Stretch tiers
- "Needs changes" - Some parts need revision before approving
- "Start over" - Fundamentally off track, re-interview
```

The approved scope tier determines what goes into specs. Items outside the chosen tier move to "Future Considerations."

**If not approved:** Revise based on feedback. If feedback reveals a fundamental misunderstanding, return to the interview loop. Otherwise re-write the HTML file and re-open in browser. Iterate until approved.

**Do not proceed until contract is explicitly approved.**

</what-to-do>

<supporting-info>

## Phase 4: Phasing & Specification

After contract is approved, determine phases and generate Markdown specs. PRDs are optional.

### 4.1 Choose Workflow

Use `AskUserQuestion` to ask:

```
Question: "How should we proceed from the contract?"
Options:
- "Straight to specs (Recommended)" — Contract defines what, specs define how. Faster.
- "PRDs then specs" — Adds a requirements layer for stakeholder alignment.
```

### 4.2 Determine Phases

Analyze the contract and break scope into logical implementation phases.

**Small-project shortcut:** If the scope is small enough to implement in a single phase (1-3 components, touches fewer than ~10 files), skip phasing entirely. Generate a single `spec.md` (no phase number needed) and proceed directly to handoff. Don't force structure where simplicity suffices.

**Phasing criteria** (for multi-phase projects):

- Dependencies (what must be built first?)
- Risk (tackle high-risk items early)
- Value delivery (can users benefit after each phase?)
- Complexity (balance phases for consistent effort)

Typical phasing:

- Phase 1: Core functionality / infrastructure
- Phase 2+: Features, enhancements, additional integrations
- Phase N: Future considerations

**Detect repeatable patterns:** If 3+ phases follow the same structure with different inputs (e.g., "add SDK support for {language}"), note this — it affects how specs are generated (see 4.4).

### 4.3 Generate PRDs (only if user chose "PRDs then specs")

For each phase, use the `Read` tool to read `references/prd-template.md`, then generate `prd-phase-{n}.md`.

Include:

- Phase overview and rationale
- User stories for this phase
- Functional requirements (grouped)
- Non-functional requirements
- Dependencies (prerequisites and outputs)
- Acceptance criteria

Present all PRDs for review via `AskUserQuestion`:

```
Question: "Do these PRD phases look correct?"
Options:
- "Approved" - Phases and requirements look good, proceed to specs
- "Adjust phases" - Need to move features between phases
- "Missing requirements" - Some requirements are missing or unclear
- "Start over" - Need to revisit the contract
```

Iterate until user explicitly approves.

### 4.4 Generate Implementation Specs

Use the `Read` tool to read `references/spec-template.md`, then generate `spec-phase-{n}.md`. Create spec files lazily — only when a phase's details are resolved.

#### Standard phases (each is unique)

For each phase, generate a full `spec-phase-{n}.md` with:

- **Technical approach** — high-level strategy
- **Feedback strategy** — inner-loop command, playground, rationale
- **File changes** — table with new/modified/deleted indicators
- **Implementation details** — per-component sections, each with a feedback loop (playground → experiment → check command)
- **Testing requirements** — table of test files and co