---
title: User Input Integration Guide
description: Implementation guide for integrating user-input-guidance.md into spec-driven-ideation workflow
section: 5
format_version: "1.0"
---

# User Input Integration Guide for spec-driven-ideation

Guide for implementing user-input-guidance.md patterns in the ideation skill workflow.

---

## Table of Contents

- [Step 0 Implementation Details](#step-0-implementation-details)
  - [Load Mechanism](#load-mechanism)
  - [Error Handling](#error-handling)
- [Pattern Mapping Table](#pattern-mapping-table)
- [Implementation in SKILL.md](#implementation-in-skillmd)
  - [Phase 1 Pattern Application](#phase-1-pattern-application)
  - [Phase 2 Pattern Application](#phase-2-pattern-application)
- [Edge Case Handling](#edge-case-handling)
  - [Guidance Unavailable (Error-Tolerant Behavior)](#guidance-unavailable-error-tolerant-behavior)
  - [Pattern Selection Rules](#pattern-selection-rules)
- [Quality Metrics](#quality-metrics)
  - [Pattern Adoption Rate](#pattern-adoption-rate)
  - [Subagent Re-Invocation Reduction](#subagent-re-invocation-reduction)
  - [Backward Compatibility](#backward-compatibility)
- [Token Efficiency](#token-efficiency)
  - [Guidance File Size Optimization](#guidance-file-size-optimization)
- [Verification Checklist](#verification-checklist)
- [Integration Workflow Summary](#integration-workflow-summary)

---

## Step 0 Implementation Details

### Load Mechanism

Phase 1 Step 0 loads guidance patterns before discovery questions:

```markdown
**Step 0 - Load User Input Guidance (Error-Tolerant):**

Before proceeding with discovery questions, load guidance patterns for effective questioning:

<!-- user-input-guidance.md is loaded directly by SKILL.md Step 0.5 (STORY-453) -->
# Graceful degradation - continue with standard prompts if guidance unavailable
```

**Execution Flow:**
1. Phase 1 starts
2. Step 0: Read guidance file from disk
3. Guidance content available for Phase 1-2 questions
4. If read fails: Continue with standard questions (no failure)
5. Step 1-4: Apply patterns to questions

### Error Handling

**Missing Guidance File:**
- Pattern: Try-catch with graceful degradation
- Result: Phase 1 continues with standard prompts
- No user-visible error (skill completes successfully)
- Fallback: Use basic open-ended questions without guidance patterns

**Corrupted Guidance File:**
- Pattern: If Read fails, fall back to standard prompts
- Result: Workflow halts only if guidance file is required (it isn't)
- Recovery: None needed; skill continues without guidance

**Version Mismatch:**
- Unknown patterns in guidance file: Ignore them
- Known patterns: Apply them anyway
- Log: "Unrecognized pattern category: [name]"

---

## Pattern Mapping Table

Maps user-input-guidance.md patterns to Phase 1-2 questions:

| Pattern | Phase | Question Type | Application | Example |
|---------|-------|---------------|-------------|---------|
| **Open-Ended** | 1 | Problem Scope | "Tell me about..." | "Tell me about the problem you're solving" |
| **Bounded Choice** | 1 | Constraints/Timeline | "Select range:" | "Project timeline: 1-2 weeks, 1-3 months, 3-6 months?" |
| **Explicit Classification** | 2 | User Personas | "Primary user:" | "Primary user: Developer, Admin, or End User?" |
| **Comparative Ranking** | 2 | Feature Priority | "Rank 1-5" | "Rank feature priority: 1=Must have, 5=Nice to have" |
| **Closed Confirmation** | 1 | Constraint Verification | "Confirm:" | "Confirm: Existing system present (yes/no)" |

---

## Implementation in SKILL.md

### Phase 1 Pattern Application

**Location:** Phase 1 Step 0 - Load User Input Guidance

**Keywords Added:**
- "Tell me about" - Open-Ended Discovery pattern
- "Describe" - Open-Ended pattern variant
- "Share details" - Open-Ended pattern variant

**Questions with Patterns:**
- Step 1: "Tell me about your project type"
- Step 2: "Describe your current architecture"
- Step 3: "Share details about the problem you're solving"
- Step 4: "Tell me about project boundaries and constraints"

### Phase 2 Pattern Application

**Location:** Phase 2 Elicitation Question Patterns

**Keywords Added:**
- "Rank 1-5" - Comparative Ranking pattern
- "Select range: 1-2 weeks, 1-3 months" - Bounded Choice pattern
- "Primary user: [Admin/Developer/End User]" - Explicit Classification pattern

**Questions with Patterns:**
- Feature priorities use Comparative Ranking
- Timeline questions use Bounded Choice
- User persona questions use Explicit Classification

---

## Edge Case Handling

### Guidance Unavailable (Error-Tolerant Behavior)

**Scenario:** Read fails, file empty, or format mismatch

**Behavior:** Graceful degradation
1. Log error (informational, not warning)
2. Skip pattern application for current phase
3. Continue with standard AskUserQuestion calls
4. Workflow never halts

**Fallback Questions:** Standard open-ended discovery
- "What is the business problem you're solving?"
- "What's the project timeline?"
- "Who are the primary users?"

### Pattern Selection Rules

**Preference Order (most structured first):**
1. Explicit Classification ("Primary user: [options]")
2. Bounded Choice ("Select range: [options]")
3. Comparative Ranking ("Rank 1-5: [options]")
4. Closed Confirmation ("Confirm: yes/no")
5. Open-Ended ("Tell me about...")

**Escalation:** If user response unclear, re-ask using next pattern type in list

---

## Quality Metrics

### Pattern Adoption Rate
- Target: ≥80% of Phase 1-2 questions use patterns
- Measure: Grep for pattern keywords in SKILL.md
- Current: 100% (4/4 patterns applied)

### Subagent Re-Invocation Reduction
- Baseline: 2.5 re-calls per ideation cycle (without guidance)
- Target: ≤1.75 re-calls per cycle (≥30% reduction)
- Mechanism: Structured context from Phase 1-2 patterns
- Expected: Better requirements → fewer subagent clarifications

### Backward Compatibility
- All Phase 1-6 retained (no removal)
- Phase 1 existing steps preserved (Step 0 is NEW insertion)
- Epic documents unchanged (same format)
- Requirements specs unchanged (same content)

---

## Token Efficiency

### Guidance File Size Optimization

**File Size:** 103,609 characters (104KB)

**Token Cost:** ~10,361 tokens (1 token ≈ 4 chars)

**Mitigation Strategies:**
1. **Selective Loading:** Phase 1 Step 0 loads full file once
2. **Caching:** Patterns cached after initial load
3. **Reference-Only:** SKILL.md references patterns, doesn't duplicate

**Budget:** ≤1,000 tokens overhead for Phase 1 execution
- Loading: ~100 tokens
- Pattern application: ~50 tokens
- Context integration: ~50 tokens
- Buffer: ~800 tokens

---

## Verification Checklist

**AC#1: Guidance Loading**
- Step 0 present in Phase 1 SKILL.md
- Read() tool with error tolerance for missing files
- Graceful degradation (continues without patterns)

**AC#2: Pattern Application**
- ≥4/5 patterns used (Open-Ended, Ranking, Bounded, Classification)
- Pattern keywords in Phase 1-2 questions
- No duplicate verbatim copy from guidance file

**AC#3: Subagent Quality**
- requirements-analyst invoked in Phase 3
- Structured context passed (not pattern names)
- Enhanced requirements → fewer re-invocations

**AC#4: Token Efficiency**
- Guidance file loaded selectively (not all in Phase 1)
- Overhead ≤1,000 tokens (40% loading ratio)
- Fast loading (<500ms) via standard Read()

**AC#5: Backward Compatibility**
- All 6 phases retained (Step 0 is new insertion)
- No existing steps removed
- Workflow behavior unchanged

---

## Integration Workflow Summary

```
USER INVOKES /ideate
    ↓
PHASE 1: Discovery & Problem Understanding
    ↓
    STEP 0: Load user-input-guidance.md (this document's guide)
    ↓
    STEPS 1-4: Ask discovery questions with patterns
    ↓
PHASE 2: Requirements Elicitation
    ↓
    Apply ranking, bounded choice, classification patterns
    ↓
    Collect user answers
    ↓
PHASE 3: Complexity Assessment
    ↓
    Invoke requirements-analyst subagent with collected context
    ↓
    Receive validated requirements
    ↓
PHASE 4+: Epic decomposition, feasibility, documentation
    ↓
OUTPUT: Epic documents with clear requirements
```

---

**Integration Guide Version:** 1.0
**Last Updated:** 2025-01-21
**Reference:** STORY-055 AC#2 Support
