Spec Driven Ideation

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-epic command for epic generation, /create-context for architecture

Execution Model

This skill expands inline. After invocation, execute Phase 00 Initialization immediately. Do not wait passively, ask permission, or offer execution options.

Self-Check (if ANY box is true = VIOLATION):

• Stopping to ask about token budget
• Stopping to offer execution options
• Waiting passively for user to say "go"
• Asking "should I execute this?"
• Skipping a phase because it "seems simple"
• Combining multiple phases into one
• Summarizing instead of loading a reference file

IF any box checked: EXECUTION MODEL VIOLATION. Go directly to Phase 00 Initialization now.

Anti-Skip Enforcement Contract

This skill enforces 4 independent anti-skip layers. ALL FOUR must fail for a step to be skipped:

1. Per-phase reference loading - Each phase loads its reference file fresh via Read(). NOT consolidated. Prevents "already covered" rationalization.
2. Checkpoint-based state tracking - Phase completion verified by checking checkpoint JSON data keys and current_phase field.
3. Artifact verification - Checkpoint JSON existence checked via Glob(), output document verified on disk.
4. Step registry with question completion - Each phase has minimum question counts and required data keys. Phase exit criteria checked before proceeding.

Execute-Verify-Record Pattern: Every mandatory step in every phase file has three parts:

• EXECUTE: The exact AskUserQuestion call, Task call, or Write call to perform
• VERIFY: How to confirm the action happened (user response non-empty, file exists, data key populated)
• RECORD: Update checkpoint JSON with captured data; increment question counter

Token Optimization Bias is PROHIBITED. Do not skip, compress, or shortcut any step. Every phase step exists because a previous failure proved it necessary.

Parameter Extraction

Extract from conversation context:

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

IF BRAINSTORM_FILE is not null and BRAINSTORM_FILE != "none":
  # Validate brainstorm file exists
  brainstorm_exists = Glob(pattern=BRAINSTORM_FILE)
  IF found:
    Read(file_path=BRAINSTORM_FILE)

    # Schema validation
    Read(file_path=".claude/skills/devforgeai-orchestration/references/skill-output-schemas.yaml")
    validation_result = validate_brainstorm_schema(brainstorm_content)

    IF validation_result == "FAILED":
      HALT: "Brainstorm schema validation failed."
    IF validation_result == "WARN":
      Display: "Brainstorm validation passed with warnings (legacy document)"
    IF validation_result == "PASSED":
      Display: "Brainstorm validation passed"

    # Pre-populate session from brainstorm
    session.brainstorm_input = {
      brainstorm_id: extract brainstorm ID from file,
      confidence_level: extract confidence from file,
      pre_populated_fields: [problem_statement, user_personas, constraints, must_haves]
    }
    session.problem_statement = brainstorm.problem_statement
    session.user_personas = brainstorm.user_personas
    session.constraints = brainstorm.hard_constraints
    session.must_have_requirements = brainstorm.must_have_capabilities
  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.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

Required Subagents

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