---
name: spec-driven-ideation
description: >
  Transform business ideas into structured requirements through guided discovery
  with structural anti-skip enforcement (Execute-Verify-Gate pattern). Applies
  per-phase reference loading, checkpoint persistence, and artifact verification
  to every step of the 7-phase ideation process. Prevents token optimization bias
  through lean orchestration. Use when users say "I have a business idea",
  "help me define requirements", "let's explore what to build", or runs /ideate.
  Do NOT use when user wants to brainstorm a vague problem (use spec-driven-brainstorming)
  or wants a business plan directly (use planning-business).
allowed-tools:
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - AskUserQuestion
  - Task
  - Skill
model: claude-opus-4-7
effort: High
version: "1.0.0"
topics: requirements, ideation, discovery, spec-driven, anti-skip, elicitation
---

# Spec-Driven Ideation

Transform business ideas into structured, actionable requirements through guided interactive questioning with structural anti-skip enforcement.

**Output:** `devforgeai/specs/requirements/{project-name}-requirements.md` (YAML per F4 schema)
**Feeds Into:** `/create-solution-architecture` command for epic generation, `/create-system-architecture` for architecture

---

## Execution Model

See **`.claude/rules/core/anti-skip-behavior.md`** for the canonical execution contract (expand inline; do not wait passively or offer execution options; honor every step of every phase; Self-Check violation taxonomy; Token-Optimization-Bias prohibition; governed by ADR-076). After invocation, execute Phase 00 Initialization immediately.

---

## Anti-Skip Enforcement Contract

Enforced structurally outside LLM control, not by this prose — by the framework's deterministic gates wired for this workflow: the `devforgeai-validate` phase gates, the `settings.json`-registered `.claude/hooks/` scripts, and `.claude/hooks/phase-steps-registry.json` (ADR-076). Behavioral residue: `.claude/rules/core/anti-skip-behavior.md`.

Layer 4 (CLI phase-gate) **is wired** as of gh#283: `ideation` is registered in `phase_state.py` `WORKFLOW_SCHEMAS`, and Phase 00 + every phase file call `phase-init` / `phase-check` / `phase-record` / `phase-complete`. The active boundary enforcer is **`pre-phase-complete-boundary-check.sh`** (PreToolUse `exit 2` when a BLOCK-policy phase file [phases 01–06] was never `Read()` during the story — ADR-132; phase-07 is EXEMPT as the terminal handoff phase; `phase-entry-validator.sh` is now PostToolUse telemetry). There are **no `[MANDATORY]` reference manifests** — ideation's reference reads stay advisory/graceful (phase-01 degrades without halting) and the generated requirements are validated downstream by `validate-pm-plan`. Step- and subagent-count enforcement stays deferred (empty `steps_required` / `subagents_required`, per ADR-110 / ADR-073).

---

## Parameter Extraction

Extract from conversation context:

| Parameter | Source | Default |
|-----------|--------|---------|
| `$BUSINESS_IDEA` | Text from `/ideate` command or `<business-idea>` XML | null (will ask in Phase 02) |
| `$BRAINSTORM_FILE` | `<brainstorm-file>` XML element from /ideate | null (no brainstorm input) |
| `$PROJECT_MODE` | `<project-mode>` XML element from /ideate | "auto-detect" |
| `$RESUME_ID` | `--resume IDEATION-NNN` argument | null (new session) |
| `$MODE` | Derived from above | "new" or "resume" |

---

## Phase 00: Initialization [INLINE - Bootstraps State]

This phase runs inline because it creates the state that all other phases depend on.

### Step 0.1: Parse Arguments

```
IF conversation contains "--resume IDEATION-":
  Extract IDEATION_ID from argument
  MODE = "resume"
ELSE IF conversation contains "<ideation-context>":
  Extract BUSINESS_IDEA from <business-idea> element
  Extract BRAINSTORM_FILE from <brainstorm-file> element
  Extract PROJECT_MODE from <project-mode> element
  MODE = "new"
ELSE IF conversation contains business idea text after /ideate:
  BUSINESS_IDEA = extracted text
  MODE = "new"
ELSE:
  MODE = "new"
  BUSINESS_IDEA = null
```

### Step 0.2: Handle Resume Mode

```
IF MODE == "resume":
  checkpoint_results = Glob(pattern="devforgeai/specs/ideation/${IDEATION_ID}.checkpoint.json")

  IF found:
    Read(file_path="devforgeai/specs/ideation/${IDEATION_ID}.checkpoint.json")
    Restore session state from checkpoint
    CURRENT_PHASE = checkpoint.progress.current_phase
    Display: "Resuming ${IDEATION_ID} from Phase ${CURRENT_PHASE}"
    GOTO Phase Orchestration Loop at CURRENT_PHASE
  ELSE:
    Display: "No checkpoint found for ${IDEATION_ID}."
    AskUserQuestion:
      Question: "No checkpoint found. What would you like to do?"
      Header: "Resume"
      Options:
        - label: "Start a new ideation session"
          description: "Begin fresh session"
        - label: "Check for completed requirements"
          description: "Look for existing requirements files"
    IF "Start new": MODE = "new", continue below
    IF "Check completed": Glob for existing requirements files, display results
```

### Step 0.3: Brainstorm Context Detection

The brainstorm file may be either format. **Branch on file extension BEFORE any field
extraction** so the wrong parser is never run against the wrong format:

- `.brainstorm.html` -> v2.0 (ADR-065): extract the embedded JSON data island.
- `.brainstorm.md`   -> v1.0 (legacy): parse YAML frontmatter.

The extension-branching extractor lives in `references/brainstorm-handoff-workflow.md`
§2.1 (`extract_brainstorm_data`). Step 0.3 calls it -- it never field-extracts inline.

```
IF BRAINSTORM_FILE is not null and BRAINSTORM_FILE != "none":
  # Validate brainstorm file exists
  brainstorm_exists = Glob(pattern=BRAINSTORM_FILE)
  IF found:
    # Load the handoff workflow reference, then extract via its extension-branching
    # extractor. Do NOT field-extract inline -- the extractor handles both .html and .md.
    Read(file_path=".claude/skills/spec-driven-ideation/references/brainstorm-handoff-workflow.md")
    brainstorm_context = extract_brainstorm_data(BRAINSTORM_FILE)   # branches on .html / .md
    brainstorm_context = validate_brainstorm_context(brainstorm_context)

    Display: "Brainstorm loaded ({brainstorm_context.source_format})."

    # Pre-populate session from the extracted context
    session.brainstorm_input = {
      brainstorm_id: brainstorm_context.brainstorm_id,
      confidence_level: brainstorm_context.confidence_level,
      source_format: brainstorm_context.source_format,
      pre_populated_fields: [problem_statement, personas, constraints, must_haves]
    }
    session = apply_brainstorm_to_ideation(brainstorm_context)   # handoff-workflow.md §3.1
  ELSE:
    Display: "Brainstorm file not found. Starting fresh."
    BRAINSTORM_FILE = null
```

### Step 0.4: Generate Session ID (New Session)

```
IF MODE == "new":
  # Scan for highest existing ID
  Glob(pattern="devforgeai/specs/ideation/IDEATION-*.checkpoint.json")
  Glob(pattern="devforgeai/specs/requirements/*-requirements.md")

  # Extract highest NNN, increment
  IDEATION_ID = "IDEATION-{NNN+1}" (zero-padded to 3 digits minimum)

  # Ensure output directories exist
  Glob(pattern="devforgeai/specs/ideation/.gitkeep")
  IF not found: Write(file_path="devforgeai/specs/ideation/.gitkeep", content="")
```

### Step 0.5: Create Initial Checkpoint

```
checkpoint = {
  "checkpoint_version": "2.0",
  "session_id": IDEATION_ID,
  "created_at": "current ISO 8601 timestamp",
  "updated_at": "current ISO 8601 timestamp",
  "status": "in_progress",
  "business_idea": BUSINESS_IDEA,
  "project_mode": PROJECT_MODE or "auto-detect",
  "brainstorm_input": {
    "brainstorm_id": session.brainstorm_input.brainstorm_id or null,
    "confidence_level": session.brainstorm_input.confidence_level or null,
    "pre_populated_fields": session.brainstorm_input.pre_populated_fields or []
  },
  "progress": {
    "current_phase": 0,
    "phases_completed": [],
    "completion_percentage": 0,
    "total_questions_asked": 0
  },
  "phases": {},
  "completed_outputs": {
    "project_type": null,
    "problem_statement": BUSINESS_IDEA or null,
    "user_types": [],
    "personas": [],
    "business_goals": [],
    "scope_boundaries": {},
    "complexity_assessment": null,
    "functional_requirements": [],
    "nfr_requirements": [],
    "data_entities": [],
    "integrations": [],
    "adr_prerequisites": [],
    "requirements_file_path": null,
    "validation_status": null,
    "next_action": null
  }
}

Write(file_path="devforgeai/specs/ideation/${IDEATION_ID}.checkpoint.json", content=checkpoint)
```

VERIFY: `Glob(pattern="devforgeai/specs/ideation/${IDEATION_ID}.checkpoint.json")`
IF not found: HALT -- "Initial checkpoint was NOT created."

### Step 0.5b: Initialize Phase-State CLI

Initialize the phase-state machine that backs the boundary gate (ADR-132). This
is the activation switch: it creates `devforgeai/workflows/${IDEATION_ID}-ideation-phase-state.json`,
which the reference-reads producer resolves so the boundary gate can verify each
phase file was loaded.

```bash
devforgeai-validate phase-init ${IDEATION_ID} --workflow=ideation --project-root=. 2>&1
```

| Exit Code | Action |
|-----------|--------|
| 0 | New workflow initialized — proceed |
| 1 | Existing workflow — resume (the checkpoint.json drives resume; continue) |
| 127 | CLI not installed — proceed without enforcement (graceful degradation) |
| Other | HALT — phase-state initialization error |

The CLI state file (`${IDEATION_ID}-ideation-phase-state.json`) backs the boundary
gate; the skill's own `${IDEATION_ID}.checkpoint.json` backs `--resume`. They
coexist — do NOT unify them. On a resumed session the existing-workflow exit (1)
is expected and non-fatal.

### Step 0.6: Display Session Banner

```
Display:
"━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  DevForgeAI Ideation Session
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Session: ${IDEATION_ID}
Mode: ${MODE == 'resume' ? 'Resumed' : 'New Ideation'}
Business Idea: ${BUSINESS_IDEA || 'To be discovered in Phase 2'}
Brainstorm Input: ${BRAINSTORM_FILE || 'None'}
Project Mode: ${PROJECT_MODE || 'Auto-detect'}

Phases: 7 (Pre-Flight > Discovery > Elicitation > Compliance > Artifacts > Validation > Handoff)
Estimated Duration: 30-90 minutes
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
```

Set CURRENT_PHASE = 1.

---

## Phase Orchestration Loop

```
FOR phase_num in range(CURRENT_PHASE, 8):  # Phases 01-07

    1. LOAD: Read(file_path=".claude/skills/spec-driven-ideation/phases/{phase_files[phase_num]}")
       Load the phase file FRESH. Do NOT rely on memory of previous reads.

    2. REFERENCE: Read the phase's reference files as specified in the phase Contract section.
       Each phase references files in .claude/skills/spec-driven-ideation/references/.
       Load ALL listed references. Do not skip any.

    3. EXECUTE: Follow EVERY step in the phase file using EXECUTE-VERIFY-RECORD triplets.
       - Each step's EXECUTE tells you exactly what AskUserQuestion to call or action to take
       - Each step's VERIFY tells you how to confirm the data was captured
       - Each step's RECORD tells you how to update the checkpoint

    4. EXIT CRITERIA: Verify ALL phase exit criteria are met before proceeding.
       IF any required data key is null or empty: HALT.
       IF questions_answered < minimum_questions: HALT.

    5. CHECKPOINT: Update checkpoint JSON with phase completion.
       Write updated checkpoint to disk.
       Verify write via Glob().

    6. CONTEXT CHECK: If estimated context > 70%, offer save-and-resume via AskUserQuestion.
       IF user chooses "Save and resume later":
         Write final checkpoint, display resume command, EXIT skill.
         Display: "Run /ideate --resume ${IDEATION_ID} to continue."
```

---

## Phase Table

| Phase | Name | File | Min Qs | Required Data |
|-------|------|------|--------|---------------|
| 00 | Initialization | (inline above) | 0-1 | session_id, checkpoint on disk |
| 01 | Pre-Flight & Context Detection | `phases/phase-01-preflight.md` | 0-3 | project_type, user_input_patterns_loaded |
| 02 | Discovery & Problem Understanding | `phases/phase-02-discovery.md` | 5 | problem_statement, user_types[>=1], business_goals[>=1], scope_boundaries |
| 03 | Requirements Elicitation | `phases/phase-03-elicitation.md` | 10 | functional_requirements[>=5], nfr_requirements[>=1], data_entities[>=1] |
| 04 | Constitutional Compliance | `phases/phase-04-compliance.md` | 0 | compliance_checked=true, adr_prerequisites (list) |
| 05 | Artifact Generation | `phases/phase-05-artifacts.md` | 0-2 | requirements_file_path (non-null, file on disk, F4 fields present) |
| 06 | Self-Validation | `phases/phase-06-validation.md` | 0-1 | validation_status in [PASSED, PASSED_WITH_WARNINGS] |
| 07 | Completion & Handoff | `phases/phase-07-handoff.md` | 1-3 | completion_summary_displayed=true, next_action_determined=true |

---

## Required Subagents

| Phase | Subagent | Enforcement |
|-------|----------|-------------|
| 01 | internet-sleuth | CONDITIONAL (if user opts for market research enrichment) |
| 04 | context-validator | CONDITIONAL (if context files exist for brownfield check) |

---

## State Persistence

- **Checkpoint:** `devforgeai/specs/ideation/${IDEATION_ID}.checkpoint.json`
- **Output:** `devforgeai/specs/requirements/{project-name}-requirements.md`
- **References:** `.claude/skills/spec-driven-ideation/references/` (shared read, not duplicated)
- **Templates:** `.claude/skills/spec-driven-ideation/assets/templates/` (shared read)
- **Scripts:** `.claude/skills/spec-driven-ideation/scripts/` (shared read)

---

## Workflow Completion Validation

```
IF phases_completed < 7: HALT "WORKFLOW INCOMPLETE - {completed_count}/7 phases"
IF requirements_file not on disk (Glob returns empty): HALT "Requirements document not generated"
IF validation_status not in [PASSED, PASSED_WITH_WARNINGS]: HALT "Validation did not pass"
IF checkpoint still exists: Mark checkpoint status = "complete"
```

---

## Error Handling

Load error recovery patterns from: `.claude/skills/spec-driven-ideation/references/error-handling-index.md`

**Error Type Files (load on-demand):**
1. `error-type-1-incomplete-answers.md` - Vague/incomplete user responses
2. `error-type-2-artifact-failures.md` - File write/permission errors
3. `error-type-3-complexity-errors.md` - Complexity assessment errors
4. `error-type-4-validation-failures.md` - Quality validation issues
5. `error-type-5-constraint-conflicts.md` - Brownfield constraint conflicts
6. `error-type-6-directory-issues.md` - Directory structure issues

**Graceful Degradation Priority:**
1. User answers (highest - never lose)
2. Problem statement
3. Functional requirements
4. Non-functional requirements
5. Data entities
6. Integrations (lowest - can be discovered later)

---

## Success Criteria

- All 7 phases executed (no skipping)
- requirements.md exists on disk with all F4 schema sections
- Validation passed (PASSED or PASSED_WITH_WARNINGS)
- User validated requirements accuracy
- Checkpoint marked as complete
- Next steps displayed to user
