Atomizer/docs/plans/ATOMIZER_STUDY_INTERVIEW_MODE_IMPLEMENTATION_PLAN.md

# Atomizer Study Interview Mode - Master Implementation Plan

**Version**: 1.0
**Created**: 2025-01-02
**Author**: Claude (Atomizer Assistant)
**Status**: Ready for Implementation
**Estimated Effort**: 1-week sprint (5-7 sessions)

---

## Table of Contents

1. [Executive Summary](#1-executive-summary)
2. [Architecture Overview](#2-architecture-overview)
3. [Component Specifications](#3-component-specifications)
4. [Implementation Phases](#4-implementation-phases)
5. [Data Schemas](#5-data-schemas)
6. [Question Engine Design](#6-question-engine-design)
7. [Intelligence Layer](#7-intelligence-layer)
8. [Integration Points](#8-integration-points)
9. [File Structure](#9-file-structure)
10. [Testing Strategy](#10-testing-strategy)
11. [Future Extensions](#11-future-extensions)

---

## 1. Executive Summary

### 1.1 Problem Statement

Currently, when creating optimization studies in Atomizer, Claude makes assumptions about:
- Which parameters to optimize
- What constraints matter
- Which extractors to use
- Appropriate bounds and thresholds

This leads to studies that may not match the engineer's actual intent, requiring multiple iterations to fix.

### 1.2 Solution

Implement an **Interview Mode** that systematically gathers engineering requirements through intelligent, adaptive questioning BEFORE study generation. The interview:

1. **Introspects** the NX model to understand what's available
2. **Interviews** the user to understand intent and requirements
3. **Validates** the configuration against engineering knowledge
4. **Generates** a blueprint for user approval
5. **Creates** the study files only after confirmation

### 1.3 Key Design Principles

| Principle | Implementation |
|-----------|----------------|
| **Talk, don't click** | Natural conversation, not forms |
| **Intelligence first** | Auto-detect what's possible, ask about intent |
| **No assumptions** | Ask instead of guessing on critical decisions |
| **Adaptive depth** | Simple studies = fewer questions |
| **Resumable** | Persist state, allow mid-interview breaks |
| **Auditable** | Log all decisions for traceability |

### 1.4 Success Criteria

- [ ] Zero assumptions on objectives, constraints, or extractors
- [ ] Interview completes in < 5 minutes for simple studies
- [ ] 100% of generated studies pass validation on first run
- [ ] Users can resume interrupted interviews
- [ ] Full audit trail of all interview decisions

---

## 2. Architecture Overview

### 2.1 High-Level Flow

\`\`\`
┌─────────────────────────────────────────────────────────────────────────────┐
│                        STUDY CREATION FLOW (UPDATED)                         │
└─────────────────────────────────────────────────────────────────────────────┘

     User Request                                                    
          │                                                          
          ▼                                                          
┌─────────────────────┐                                              
│  1. TRIGGER DETECT  │  "Create study for bracket optimization"     
│     (Router)        │  Detects: new study, sub-study, or resume    
└──────────┬──────────┘                                              
           │                                                          
           ▼                                                          
┌─────────────────────┐     ┌─────────────────────┐                  
│  2. INTROSPECTION   │────▶│  Model Intelligence │                  
│     (Automatic)     │     │  - Expressions      │                  
│                     │     │  - Solutions        │                  
│                     │     │  - Results          │                  
│                     │     │  - Materials        │                  
└──────────┬──────────┘     └─────────────────────┘                  
           │                                                          
           ▼                                                          
┌─────────────────────┐     ┌─────────────────────┐                  
│  3. INTERVIEW MODE  │◀───▶│  Question Engine    │                  
│     (Interactive)   │     │  - Adaptive flow    │                  
│                     │     │  - Validation       │                  
│                     │     │  - State management │                  
└──────────┬──────────┘     └─────────────────────┘                  
           │                                                          
           ▼                                                          
┌─────────────────────┐     ┌─────────────────────┐                  
│  4. BLUEPRINT GEN   │────▶│  Study Blueprint    │                  
│     (Review)        │     │  - Config preview   │                  
│                     │     │  - What-if mods     │                  
└──────────┬──────────┘     └─────────────────────┘                  
           │                                                          
           ▼                                                          
┌─────────────────────┐     ┌─────────────────────┐                  
│  5. VALIDATION      │────▶│  Baseline Check     │                  
│     (Optional)      │     │  - Run single solve │                  
│                     │     │  - Verify extractors│                  
└──────────┬──────────┘     └─────────────────────┘                  
           │                                                          
           ▼                                                          
┌─────────────────────┐     ┌─────────────────────┐                  
│  6. GENERATION      │────▶│  Study Files        │                  
│     (Final)         │     │  - Config JSON      │                  
│                     │     │  - Runner script    │                  
│                     │     │  - Documentation    │                  
└─────────────────────┘     └─────────────────────┘                  
\`\`\`

### 2.2 Component Architecture

\`\`\`
┌─────────────────────────────────────────────────────────────────────────────┐
│                           INTERVIEW SYSTEM ARCHITECTURE                      │
└─────────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│                              PRESENTATION LAYER                              │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐             │
│  │ Claude Convo    │  │ Dashboard UI    │  │ CLI Wizard      │             │
│  │ (VS Code/Web)   │  │ (Future)        │  │ (Future)        │             │
│  └────────┬────────┘  └────────┬────────┘  └────────┬────────┘             │
│           │                    │                    │                       │
│           └────────────────────┼────────────────────┘                       │
│                                │                                            │
│                                ▼                                            │
│                    ┌─────────────────────┐                                  │
│                    │ Interview Presenter │  (Abstraction Layer)             │
│                    │ - Format questions  │                                  │
│                    │ - Parse responses   │                                  │
│                    │ - Handle UI events  │                                  │
│                    └──────────┬──────────┘                                  │
└───────────────────────────────┼─────────────────────────────────────────────┘
                                │
┌───────────────────────────────┼─────────────────────────────────────────────┐
│                               ▼              CORE LAYER                      │
│                    ┌─────────────────────┐                                  │
│                    │  Interview Engine   │                                  │
│                    │  - State machine    │                                  │
│                    │  - Question routing │                                  │
│                    │  - Answer handling  │                                  │
│                    └──────────┬──────────┘                                  │
│                               │                                             │
│           ┌───────────────────┼───────────────────┐                         │
│           ▼                   ▼                   ▼                         │
│  ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐               │
│  │ Question Engine │ │ State Manager   │ │ Validator       │               │
│  │ - Schema loader │ │ - Persistence   │ │ - Engineering   │               │
│  │ - Conditionals  │ │ - Resume/save   │ │ - Bounds check  │               │
│  │ - Dynamic opts  │ │ - History       │ │ - Anti-patterns │               │
│  └────────┬────────┘ └────────┬────────┘ └────────┬────────┘               │
│           │                   │                   │                         │
└───────────┼───────────────────┼───────────────────┼─────────────────────────┘
            │                   │                   │
┌───────────┼───────────────────┼───────────────────┼─────────────────────────┐
│           ▼                   ▼                   ▼     INTELLIGENCE LAYER   │
│  ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐               │
│  │ Question Schema │ │ Interview Store │ │ Knowledge Base  │               │
│  │ (JSON/YAML)     │ │ (JSON files)    │ │ - Materials DB  │               │
│  │ - Categories    │ │ - State per     │ │ - Extractor map │               │
│  │ - Conditions    │ │   study         │ │ - Anti-patterns │               │
│  │ - Validations   │ │ - Audit logs    │ │ - Study history │               │
│  └─────────────────┘ └─────────────────┘ └─────────────────┘               │
└─────────────────────────────────────────────────────────────────────────────┘
\`\`\`

### 2.3 Data Flow

\`\`\`
┌─────────────────────────────────────────────────────────────────────────────┐
│                              DATA FLOW DIAGRAM                               │
└─────────────────────────────────────────────────────────────────────────────┘

  NX Model (.prt, .sim)                      User Input
         │                                        │
         ▼                                        ▼
  ┌─────────────┐                         ┌─────────────┐
  │Introspection│                         │  Question   │
  │   Results   │                         │  Responses  │
  └──────┬──────┘                         └──────┬──────┘
         │                                        │
         │         ┌─────────────────┐           │
         └────────▶│ Interview State │◀──────────┘
                   │     (JSON)      │
                   └────────┬────────┘
                            │
              ┌─────────────┼─────────────┐
              ▼             ▼             ▼
       ┌───────────┐ ┌───────────┐ ┌───────────┐
       │ Blueprint │ │ Audit Log │ │Validation │
       │  (JSON)   │ │   (MD)    │ │  Results  │
       └─────┬─────┘ └───────────┘ └───────────┘
             │
             ▼
  ┌─────────────────────────────────────────────┐
  │              Study Generation               │
  │  ┌─────────────┐  ┌─────────────┐          │
  │  │optimization_│  │    run_     │  + more  │
  │  │ config.json │  │optimization │          │
  │  └─────────────┘  │    .py      │          │
  │                   └─────────────┘          │
  └─────────────────────────────────────────────┘
\`\`\`

---

## 3. Component Specifications

### 3.1 Interview Engine (\`study_interview.py\`)

**Purpose**: Core orchestrator for the interview process.

**Responsibilities**:
- Manage interview state machine
- Route to appropriate question categories
- Handle answer validation
- Coordinate with introspection
- Generate blueprint from collected answers

**Key Classes**:

\`\`\`python
class StudyInterviewEngine:
    """Main orchestrator for study interviews."""
    
    def __init__(self, study_path: Path, presenter: InterviewPresenter):
        self.study_path = study_path
        self.presenter = presenter
        self.state_manager = InterviewStateManager(study_path)
        self.question_engine = QuestionEngine()
        self.validator = EngineeringValidator()
        self.intelligence = InterviewIntelligence()
    
    def start_interview(self, model_path: Path) -> InterviewSession:
        """Start a new interview or resume existing one."""
        pass
    
    def process_answer(self, answer: str) -> NextAction:
        """Process user answer and determine next action."""
        pass
    
    def generate_blueprint(self) -> StudyBlueprint:
        """Generate study blueprint from interview state."""
        pass
    
    def modify_blueprint(self, changes: dict) -> StudyBlueprint:
        """Allow what-if modifications without restarting."""
        pass


class InterviewSession:
    """Represents an active interview session."""
    
    session_id: str
    study_name: str
    started_at: datetime
    current_phase: InterviewPhase
    introspection: IntrospectionResults
    answers: Dict[str, Any]
    is_complete: bool


class NextAction:
    """What should happen after processing an answer."""
    
    action_type: Literal["ask_question", "show_summary", "validate", "generate", "error"]
    question: Optional[Question]
    message: Optional[str]
    warnings: List[str]
\`\`\`

### 3.2 Question Engine (\`question_engine.py\`)

**Purpose**: Manage question definitions, conditions, and dynamic options.

**Responsibilities**:
- Load question schemas from JSON/YAML
- Evaluate conditional logic
- Populate dynamic options from introspection
- Track question dependencies

**Key Classes**:

\`\`\`python
class QuestionEngine:
    """Manages question definitions and flow logic."""
    
    def __init__(self, schema_path: Path = None):
        self.schema = self._load_schema(schema_path)
        self.categories = self._build_categories()
    
    def get_next_question(
        self, 
        current_state: InterviewState,
        introspection: IntrospectionResults
    ) -> Optional[Question]:
        """Determine the next question based on state and conditions."""
        pass
    
    def evaluate_condition(
        self, 
        condition: QuestionCondition, 
        state: InterviewState
    ) -> bool:
        """Evaluate if a question's condition is met."""
        pass
    
    def populate_options(
        self, 
        question: Question, 
        introspection: IntrospectionResults
    ) -> Question:
        """Fill in dynamic options from introspection data."""
        pass


class Question:
    """Represents a single interview question."""
    
    id: str
    category: str
    text: str
    help_text: Optional[str]
    question_type: Literal["text", "choice", "multi_choice", "numeric", "confirm"]
    options: Optional[List[QuestionOption]]
    default: Optional[Any]
    validation: Optional[ValidationRule]
    condition: Optional[QuestionCondition]
    maps_to: str  # Config field this populates
    engineering_guidance: Optional[str]


class QuestionCondition:
    """Conditional logic for when to ask a question."""
    
    type: Literal["answered", "equals", "contains", "introspection_has", "and", "or", "not"]
    field: Optional[str]
    value: Optional[Any]
    conditions: Optional[List["QuestionCondition"]]  # For and/or/not
\`\`\`

### 3.3 State Manager (\`interview_state.py\`)

**Purpose**: Persist and manage interview state across sessions.

**Responsibilities**:
- Save/load interview state to JSON
- Generate human-readable audit log (MD)
- Track modification history
- Support resume from any point

**Key Classes**:

\`\`\`python
class InterviewStateManager:
    """Manages interview state persistence."""
    
    def __init__(self, study_path: Path):
        self.study_path = study_path
        self.interview_dir = study_path / ".interview"
        self.state_file = self.interview_dir / "interview_state.json"
        self.log_file = self.interview_dir / "INTERVIEW_LOG.md"
    
    def save_state(self, state: InterviewState) -> None:
        """Persist current state to JSON."""
        pass
    
    def load_state(self) -> Optional[InterviewState]:
        """Load existing state if available."""
        pass
    
    def append_log(self, entry: LogEntry) -> None:
        """Add entry to human-readable audit log."""
        pass
    
    def get_history(self) -> List[StateSnapshot]:
        """Get modification history for undo/branch."""
        pass


class InterviewState:
    """Complete interview state (JSON-serializable)."""
    
    version: str = "1.0"
    session_id: str
    study_name: str
    study_path: str
    
    # Progress tracking
    started_at: str  # ISO datetime
    last_updated: str
    current_phase: str
    questions_asked: List[str]
    questions_remaining: List[str]
    
    # Introspection cache
    introspection: Dict[str, Any]
    
    # Collected answers
    answers: Dict[str, Any]
    
    # Derived configuration
    inferred_config: Dict[str, Any]
    
    # Validation results
    warnings: List[str]
    errors: List[str]
    
    # Blueprint (when complete)
    blueprint: Optional[Dict[str, Any]]
\`\`\`

### 3.4 Engineering Validator (\`engineering_validator.py\`)

**Purpose**: Validate answers against engineering knowledge and detect anti-patterns.

**Responsibilities**:
- Validate material properties and limits
- Detect optimization anti-patterns
- Check constraint feasibility
- Provide engineering guidance

**Key Classes**:

\`\`\`python
class EngineeringValidator:
    """Validates interview answers against engineering knowledge."""
    
    def __init__(self):
        self.materials_db = MaterialsDatabase()
        self.anti_patterns = AntiPatternDetector()
    
    def validate_constraint(
        self, 
        constraint_type: str,
        value: float,
        material: Optional[str],
        baseline: Optional[float]
    ) -> ValidationResult:
        """Validate a constraint value against engineering limits."""
        pass
    
    def detect_anti_patterns(
        self, 
        state: InterviewState
    ) -> List[AntiPattern]:
        """Detect common optimization anti-patterns."""
        pass
    
    def suggest_bounds(
        self, 
        parameter: str,
        current_value: float,
        context: Dict[str, Any]
    ) -> Tuple[float, float]:
        """Suggest reasonable bounds for a design variable."""
        pass


class MaterialsDatabase:
    """Database of common engineering materials and properties."""
    
    def get_material(self, name: str) -> Optional[Material]:
        """Look up material by name (fuzzy matching)."""
        pass
    
    def get_yield_stress(self, material: str) -> Optional[float]:
        """Get yield stress for material in MPa."""
        pass
    
    def validate_stress_limit(
        self, 
        material: str, 
        limit: float,
        safety_factor: float = 1.0
    ) -> ValidationResult:
        """Check if stress limit is reasonable for material."""
        pass


class AntiPatternDetector:
    """Detects common optimization setup mistakes."""
    
    PATTERNS = [
        "mass_minimization_no_constraint",
        "modal_static_single_solution",
        "bounds_too_wide",
        "conflicting_objectives",
        "missing_stress_constraint",
        # ... more patterns
    ]
    
    def check_all(self, state: InterviewState) -> List[AntiPattern]:
        """Run all anti-pattern checks."""
        pass
\`\`\`

### 3.5 Interview Presenter (\`interview_presenter.py\`)

**Purpose**: Abstract presentation layer for different UI modes.

**Responsibilities**:
- Format questions for display
- Parse user responses
- Handle UI-specific interactions
- Support multiple presentation modes

**Key Classes**:

\`\`\`python
class InterviewPresenter(ABC):
    """Abstract base for interview presentation."""
    
    @abstractmethod
    def present_question(self, question: Question) -> None:
        """Display a question to the user."""
        pass
    
    @abstractmethod
    def get_response(self) -> str:
        """Get user's response."""
        pass
    
    @abstractmethod
    def show_summary(self, blueprint: StudyBlueprint) -> None:
        """Display interview summary/blueprint."""
        pass
    
    @abstractmethod
    def show_warning(self, warning: str) -> None:
        """Display a warning message."""
        pass


class ClaudePresenter(InterviewPresenter):
    """Presenter for Claude conversation mode (VS Code, Web)."""
    
    def format_question_markdown(self, question: Question) -> str:
        """Format question as markdown for Claude to present."""
        pass
    
    def parse_natural_response(self, response: str, question: Question) -> Any:
        """Parse natural language response into structured answer."""
        pass


class DashboardPresenter(InterviewPresenter):
    """Presenter for dashboard UI mode (future)."""
    
    def emit_question_event(self, question: Question) -> None:
        """Emit WebSocket event for dashboard to render."""
        pass


class CLIPresenter(InterviewPresenter):
    """Presenter for CLI wizard mode (future)."""
    
    def prompt_user(self, question: Question) -> str:
        """Interactive CLI prompt."""
        pass
\`\`\`

### 3.6 Interview Intelligence (\`interview_intelligence.py\`)

**Purpose**: Smart features - auto-detection, inference, and learning.

**Responsibilities**:
- Infer study type from context
- Auto-select extractors based on goals
- Learn from previous studies
- Provide intelligent defaults

**Key Classes**:

\`\`\`python
class InterviewIntelligence:
    """Smart features for interview process."""
    
    def __init__(self):
        self.extractor_mapper = ExtractorMapper()
        self.study_history = StudyHistoryAnalyzer()
    
    def infer_study_type(
        self, 
        study_name: str,
        user_description: str,
        introspection: IntrospectionResults
    ) -> StudyTypeInference:
        """Infer study type from available context."""
        pass
    
    def auto_select_extractors(
        self, 
        objectives: List[Objective],
        constraints: List[Constraint],
        introspection: IntrospectionResults
    ) -> Dict[str, str]:
        """Automatically select appropriate extractors."""
        pass
    
    def suggest_from_history(
        self, 
        model_path: Path,
        goal: str
    ) -> Optional[HistorySuggestion]:
        """Suggest configuration based on previous studies with same model."""
        pass
    
    def determine_complexity(
        self, 
        state: InterviewState
    ) -> Literal["simple", "moderate", "complex"]:
        """Determine study complexity for adaptive questioning."""
        pass


class ExtractorMapper:
    """Maps physics goals to appropriate extractors."""
    
    MAPPING = {
        "displacement": "E1",
        "deflection": "E1",
        "stiffness": "E1",  # inverse
        "frequency": "E2",
        "natural_frequency": "E2",
        "modal": "E2",
        "stress": "E3",
        "von_mises": "E3",
        "mass": "E4",  # from BDF
        "weight": "E4",
        # ... complete mapping
    }
    
    def map_goal_to_extractor(
        self, 
        goal: str,
        introspection: IntrospectionResults
    ) -> ExtractorSelection:
        """Map a physics goal to the appropriate extractor."""
        pass
\`\`\`

---

## 4. Implementation Phases

### Phase 1: Foundation (Sessions 1-2)

**Goal**: Core infrastructure and basic interview flow.

**Deliverables**:
1. \`study_interview.py\` - Interview engine skeleton
2. \`interview_state.py\` - State management with JSON persistence
3. \`question_engine.py\` - Basic question loading and flow
4. \`interview_schema.json\` - Initial question definitions
5. \`study-interview-mode.md\` - Skill file for Claude

**Tasks**:
\`\`\`
□ Create optimization_engine/interview/ directory structure
□ Implement InterviewState dataclass with JSON serialization
□ Implement InterviewStateManager with save/load
□ Create basic question schema JSON structure
□ Implement QuestionEngine with simple linear flow
□ Implement StudyInterviewEngine orchestrator
□ Create ClaudePresenter for markdown formatting
□ Write skill file with interview protocol
□ Test: Start interview, answer questions, save state
\`\`\`

**Exit Criteria**:
- Can start a new interview
- Questions load from JSON schema
- State persists across sessions
- Claude can present questions via skill

### Phase 2: Intelligence (Sessions 3-4)

**Goal**: Smart features - introspection integration, auto-detection, conditional logic.

**Deliverables**:
1. \`interview_intelligence.py\` - Auto-selection and inference
2. \`engineering_validator.py\` - Basic validation
3. Updated \`interview_schema.json\` - Conditional questions
4. Integration with existing introspection system

**Tasks**:
\`\`\`
□ Integrate with introspect_part(), introspect_simulation(), introspect_op2()
□ Implement ExtractorMapper for goal→extractor mapping
□ Implement conditional question logic in QuestionEngine
□ Implement dynamic option population from introspection
□ Add expression name heuristics for design variable suggestions
□ Implement basic MaterialsDatabase with common materials
□ Add stress limit validation against material properties
□ Implement complexity determination logic
□ Test: Interview with real NX model, verify auto-selections
\`\`\`

**Exit Criteria**:
- Introspection runs automatically at interview start
- Extractors auto-selected based on stated goals
- Design variables suggested from expressions
- Material-based validation works

### Phase 3: Validation & Anti-Patterns (Session 5)

**Goal**: Engineering validation and anti-pattern detection.

**Deliverables**:
1. Complete \`engineering_validator.py\`
2. \`anti_patterns.json\` - Pattern definitions
3. Baseline validation integration
4. Warning/error system

**Tasks**:
\`\`\`
□ Implement AntiPatternDetector with pattern definitions
□ Add patterns: mass_no_constraint, modal_single_solution, bounds_wide, etc.
□ Implement baseline validation trigger (optional solve)
□ Add feasibility checks (constraint vs baseline)
□ Implement warning aggregation and presentation
□ Add "proceed anyway" flow for warnings
□ Test: Trigger each anti-pattern, verify warnings
\`\`\`

**Exit Criteria**:
- Anti-patterns detected and warned
- Baseline validation can run
- Feasibility checked against baseline
- User can acknowledge warnings and proceed

### Phase 4: Blueprint & Generation (Session 6)

**Goal**: Blueprint generation, review, and study file creation.

**Deliverables**:
1. \`study_blueprint.py\` - Blueprint data structures
2. Blueprint review flow
3. What-if modification support
4. Integration with existing StudyWizard for generation

**Tasks**:
\`\`\`
□ Implement StudyBlueprint dataclass
□ Implement blueprint generation from interview state
□ Create blueprint review presentation (markdown summary)
□ Implement modify_blueprint() for what-if changes
□ Implement branching (save current, try modification)
□ Integrate with StudyWizard.generate() for file creation
□ Generate INTERVIEW_LOG.md audit trail
□ Test: Complete interview → blueprint → modify → generate
\`\`\`

**Exit Criteria**:
- Blueprint generated from interview
- User can review and modify
- What-if changes without restart
- Study files generated correctly

### Phase 5: Polish & Integration (Session 7)

**Goal**: Full integration, edge cases, documentation.

**Deliverables**:
1. Updated \`OP_01_CREATE_STUDY.md\` with interview phase
2. Complete test coverage
3. Error handling for all edge cases
4. Documentation updates

**Tasks**:
\`\`\`
□ Update OP_01 protocol with interview phase
□ Update 00_BOOTSTRAP.md task routing
□ Update 02_CONTEXT_LOADER.md
□ Add sub-study detection (skip option)
□ Handle interview resume edge cases
□ Complete error handling
□ Write unit tests for all components
□ Integration test: full flow from trigger to generation
□ Update CLAUDE.md with interview instructions
□ Create example interview transcripts
\`\`\`

**Exit Criteria**:
- Full flow works end-to-end
- Edge cases handled gracefully
- Documentation complete
- Tests pass

---

## 5. Data Schemas

### 5.1 Interview State Schema (\`interview_state.json\`)

\`\`\`json
{
  "\$schema": "http://json-schema.org/draft-07/schema#",
  "title": "InterviewState",
  "type": "object",
  "required": ["version", "session_id", "study_name", "current_phase", "answers"],
  "properties": {
    "version": {
      "type": "string",
      "const": "1.0"
    },
    "session_id": {
      "type": "string",
      "format": "uuid"
    },
    "study_name": {
      "type": "string"
    },
    "study_path": {
      "type": "string"
    },
    "parent_study": {
      "type": ["string", "null"],
      "description": "Parent study path if this is a sub-study"
    },
    "started_at": {
      "type": "string",
      "format": "date-time"
    },
    "last_updated": {
      "type": "string",
      "format": "date-time"
    },
    "current_phase": {
      "type": "string",
      "enum": ["introspection", "problem_definition", "objectives", "constraints", "design_variables", "validation", "review", "complete"]
    },
    "complexity": {
      "type": "string",
      "enum": ["simple", "moderate", "complex"]
    },
    "questions_answered": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "question_id": { "type": "string" },
          "answered_at": { "type": "string", "format": "date-time" },
          "raw_response": { "type": "string" },
          "parsed_value": {}
        }
      }
    },
    "introspection": {
      "type": "object",
      "properties": {
        "part_file": { "type": "string" },
        "sim_file": { "type": ["string", "null"] },
        "expressions": { "type": "array" },
        "solutions": { "type": "array" },
        "available_results": { "type": "object" },
        "element_types": { "type": "array" },
        "material": { "type": ["object", "null"] },
        "baseline_results": { "type": ["object", "null"] }
      }
    },
    "answers": {
      "type": "object",
      "properties": {
        "problem_description": { "type": "string" },
        "physical_context": { "type": "string" },
        "objectives": { "type": "array" },
        "constraints": { "type": "array" },
        "design_variables": { "type": "array" },
        "protocol": { "type": "string" },
        "n_trials": { "type": "integer" },
        "use_neural_acceleration": { "type": "boolean" }
      }
    },
    "warnings": { "type": "array" },
    "blueprint": { "type": ["object", "null"] }
  }
}
\`\`\`

### 5.2 Materials Database Schema

\`\`\`json
{
  "version": "1.0",
  "materials": [
    {
      "id": "al_6061_t6",
      "names": ["aluminum 6061-t6", "al6061-t6", "6061-t6", "al 6061"],
      "category": "aluminum",
      "properties": {
        "density_kg_m3": 2700,
        "yield_stress_mpa": 276,
        "ultimate_stress_mpa": 310,
        "elastic_modulus_gpa": 68.9,
        "poisson_ratio": 0.33,
        "fatigue_limit_mpa": 96
      },
      "notes": "Common aerospace aluminum alloy"
    },
    {
      "id": "al_2024_t3",
      "names": ["aluminum 2024-t3", "al2024-t3", "2024-t3"],
      "category": "aluminum",
      "properties": {
        "density_kg_m3": 2780,
        "yield_stress_mpa": 345,
        "ultimate_stress_mpa": 483,
        "elastic_modulus_gpa": 73.1,
        "poisson_ratio": 0.33
      },
      "notes": "High-strength aerospace aluminum"
    },
    {
      "id": "steel_304",
      "names": ["stainless steel 304", "ss304", "304 stainless"],
      "category": "steel",
      "properties": {
        "density_kg_m3": 8000,
        "yield_stress_mpa": 215,
        "ultimate_stress_mpa": 505,
        "elastic_modulus_gpa": 193,
        "poisson_ratio": 0.29
      }
    },
    {
      "id": "ti_6al_4v",
      "names": ["titanium 6al-4v", "ti-6al-4v", "ti64"],
      "category": "titanium",
      "properties": {
        "density_kg_m3": 4430,
        "yield_stress_mpa": 880,
        "ultimate_stress_mpa": 950,
        "elastic_modulus_gpa": 113.8,
        "poisson_ratio": 0.342
      },
      "notes": "Common aerospace titanium alloy"
    }
  ]
}
\`\`\`

---

## 6. Question Engine Design

### 6.1 Question Categories

\`\`\`yaml
categories:
  - id: problem_definition
    name: "Problem Definition"
    phase: problem_definition
    order: 1
    always_ask: true
    
  - id: objectives
    name: "Optimization Objectives"
    phase: objectives
    order: 2
    always_ask: true
    
  - id: constraints
    name: "Constraints & Limits"
    phase: constraints
    order: 3
    always_ask: true
    
  - id: design_variables
    name: "Design Variables"
    phase: design_variables
    order: 4
    always_ask: true
    
  - id: physics_config
    name: "Physics Configuration"
    phase: design_variables
    order: 5
    condition: { complexity_is: ["moderate", "complex"] }
    
  - id: optimization_settings
    name: "Optimization Settings"
    phase: validation
    order: 6
    condition: { complexity_is: ["moderate", "complex"] }
    
  - id: validation
    name: "Validation"
    phase: validation
    order: 7
    always_ask: false
\`\`\`

### 6.2 Core Questions (Summary)

| ID | Category | Question | Type | Condition |
|----|----------|----------|------|-----------|
| pd_01 | Problem Definition | What engineering problem are you solving? | text | always |
| pd_02 | Problem Definition | What's the physical context? | text | moderate+ |
| pd_03 | Problem Definition | What type of analysis? | multi_choice | always |
| obj_01 | Objectives | Primary optimization goal? | choice | always |
| obj_02 | Objectives | Secondary objectives? | multi_choice | always |
| obj_03 | Objectives | Confirm extractor selection | confirm | always |
| con_01 | Constraints | Max allowable stress? | numeric | has_stress |
| con_02 | Constraints | Max allowable displacement? | numeric | has_disp |
| con_03 | Constraints | Min frequency? | numeric | has_modal |
| con_04 | Constraints | Mass budget? | numeric | not_min_mass |
| con_05 | Constraints | Hard or soft constraints? | choice | always |
| dv_01 | Design Variables | Select parameters to vary | parameter_select | always |
| dv_02 | Design Variables | Confirm bounds | bounds | always |
| dv_03 | Design Variables | Fixed parameters? | parameter_select | complex |
| phys_01 | Physics | Element type? | choice | needs_stress |
| phys_02 | Physics | Solve all solutions? | confirm | multi_solution |
| opt_01 | Settings | Number of trials? | choice | moderate+ |
| opt_02 | Settings | Neural acceleration? | confirm | trials>100 |
| val_01 | Validation | Run baseline? | confirm | recommended |

---

## 7. Intelligence Layer

### 7.1 Extractor Auto-Selection Logic

\`\`\`python
GOAL_TO_EXTRACTOR_MAP = {
    "minimize_mass": {"extractor": "E4", "fallback": "E5"},
    "maximize_stiffness": {"extractor": "E1", "goal": "minimize"},
    "minimize_displacement": {"extractor": "E1", "goal": "minimize"},
    "minimize_stress": {"extractor": "E3", "params": {"element_type": "auto"}},
    "maximize_frequency": {"extractor": "E2", "params": {"mode_number": 1}},
    "target_frequency": {"extractor": "E2", "goal": "target"},
    "minimize_wavefront_error": {"extractor": "E8", "complexity": "complex"}
}
\`\`\`

### 7.2 Anti-Pattern Detection

| Pattern ID | Description | Severity | Condition |
|------------|-------------|----------|-----------|
| mass_no_constraint | Minimizing mass without constraints | error | minimize_mass AND no constraints |
| modal_single_solution | Modal+static but single solution | error | modal AND static AND not solve_all |
| bounds_too_wide | Bounds span >10x range | warning | max/min > 10 |
| stress_over_yield | Stress limit > material yield | warning | limit > yield_stress |
| conflicting_objectives | Typically conflicting goals | info | mass vs stiffness |
| too_many_objectives | More than 3 objectives | warning | len(objectives) > 3 |

### 7.3 Design Variable Name Heuristics

**High confidence patterns**: thickness, width, height, diameter, radius, length, depth, angle, fillet, chamfer

**Medium confidence patterns**: dim_*, size_*, param_*, p[0-9]+, var_*

**Exclude patterns**: mesh_*, count_*, num_*, material*, derived_*, calc_*

### 7.4 Complexity Determination

\`\`\`python
def determine_complexity(state, introspection):
    score = 0
    
    # Objectives
    n_obj = len(state.objectives)
    score += 0 if n_obj == 1 else (1 if n_obj == 2 else 2)
    
    # Design variables
    n_dvs = len(state.design_variables)
    score += 0 if n_dvs <= 3 else (1 if n_dvs <= 6 else 2)
    
    # Analysis type
    if "coupled" in state.analysis_types or len(state.analysis_types) > 2:
        score += 2
    elif len(state.analysis_types) > 1:
        score += 1
    
    # Custom components
    if state.custom_extractor or state.custom_processing:
        score += 2
    
    # Categorize
    if score <= 2: return "simple"
    elif score <= 5: return "moderate"
    else: return "complex"
\`\`\`

---

## 8. Integration Points

### 8.1 Integration with StudyWizard

\`\`\`python
# optimization_engine/study_wizard.py (MODIFIED)

class StudyWizard:
    @classmethod
    def from_interview(cls, interview_state: InterviewState) -> "StudyWizard":
        """Create StudyWizard from completed interview."""
        wizard = cls(
            study_name=interview_state.study_name,
            description=interview_state.answers.get("problem_description", "")
        )
        
        # Transfer design variables
        for dv in interview_state.answers.get("design_variables", []):
            wizard.add_design_variable(
                parameter=dv["parameter"],
                bounds=tuple(dv["bounds"]),
                units=dv.get("units", "")
            )
        
        # Transfer objectives
        for obj in interview_state.answers.get("objectives", []):
            wizard.add_objective(
                name=obj["name"],
                goal=obj["goal"],
                extractor=obj["extractor"],
                params=obj.get("extractor_params", {})
            )
        
        # Transfer constraints
        for con in interview_state.answers.get("constraints", []):
            wizard.add_constraint(
                name=con["name"],
                constraint_type=con["type"],
                threshold=con["threshold"],
                extractor=con["extractor"]
            )
        
        # Set protocol
        n_objectives = len(interview_state.answers.get("objectives", []))
        wizard.set_protocol(
            "protocol_11_multi" if n_objectives > 1 else "protocol_10_single"
        )
        
        wizard.set_trials(interview_state.answers.get("n_trials", 100))
        wizard.introspection = interview_state.introspection
        
        return wizard
\`\`\`

### 8.2 Updated OP_01_CREATE_STUDY Protocol

\`\`\`markdown
# OP_01: Create Optimization Study (UPDATED)

## Study Creation Flow

1. TRIGGER DETECTION → New study / Sub-study / Resume
2. INTROSPECTION (Automatic) → expressions, solutions, results
3. INTERVIEW MODE (Interactive) → questions, validation, anti-patterns
4. BLUEPRINT REVIEW → preview, modifications
5. BASELINE VALIDATION (Recommended) → single solve check
6. STUDY GENERATION → config, runner, docs
\`\`\`

---

## 9. File Structure

### 9.1 New Files to Create

\`\`\`
Atomizer/
├── optimization_engine/
│   └── interview/                      # NEW DIRECTORY
│       ├── __init__.py
│       ├── study_interview.py          # Main interview engine
│       ├── question_engine.py          # Question management
│       ├── interview_state.py          # State persistence
│       ├── interview_presenter.py      # Presentation abstraction
│       ├── interview_intelligence.py   # Smart features
│       ├── engineering_validator.py    # Validation & anti-patterns
│       └── schemas/
│           ├── interview_questions.json
│           ├── materials_database.json
│           └── anti_patterns.json
│
├── .claude/skills/core/
│   └── study-interview-mode.md         # NEW SKILL
│
├── docs/protocols/operations/
│   └── OP_01_CREATE_STUDY.md           # UPDATED
│
└── tests/interview/                    # NEW TEST DIRECTORY
    ├── test_interview_engine.py
    ├── test_question_engine.py
    ├── test_state_manager.py
    └── test_engineering_validator.py
\`\`\`

### 9.2 Study Directory Structure (Updated)

\`\`\`
studies/{study_name}/
├── .interview/                         # NEW
│   ├── interview_state.json            # Machine-readable state
│   └── INTERVIEW_LOG.md                # Human-readable audit
├── 1_setup/
│   ├── model/
│   └── optimization_config.json
├── 2_results/
├── 3_reports/
├── run_optimization.py
├── README.md
├── MODEL_INTROSPECTION.md
└── STUDY_REPORT.md
\`\`\`

---

## 10. Testing Strategy

### 10.1 Unit Tests

- \`test_interview_engine.py\`: Start, resume, process answers
- \`test_question_engine.py\`: Schema loading, conditions, dynamic options
- \`test_state_manager.py\`: Save, load, history
- \`test_engineering_validator.py\`: Material validation, anti-patterns

### 10.2 Integration Tests

- Complete simple interview flow
- Interview state persistence across restart
- Full flow from interview to study generation

---

## 11. Future Extensions

### 11.1 Dashboard Integration (Phase 2)
- React component \`InterviewWizard.tsx\`
- WebSocket connection to interview engine
- Form-based question rendering

### 11.2 CLI Wizard Mode (Phase 2)
- Interactive terminal wizard using Rich/Questionary
- Same engine, different presenter

### 11.3 Study Templates (Phase 3)
- Pre-filled interviews for common patterns
- "Structural Mass Minimization", "Frequency Tuning", etc.

### 11.4 Learning from History (Phase 3)
- Record interview outcomes
- Suggest from similar past studies
- Improve over time

---

## 12. Implementation Checklist

### Session 1-2: Foundation
- [ ] Create interview/ directory structure
- [ ] Implement InterviewState dataclass
- [ ] Implement InterviewStateManager
- [ ] Create interview_questions.json
- [ ] Implement QuestionEngine
- [ ] Implement StudyInterviewEngine
- [ ] Create ClaudePresenter
- [ ] Write study-interview-mode.md skill

### Session 3-4: Intelligence
- [ ] Integrate introspection functions
- [ ] Implement ExtractorMapper
- [ ] Implement conditional logic
- [ ] Add expression name heuristics
- [ ] Create materials_database.json
- [ ] Implement complexity determination

### Session 5: Validation
- [ ] Implement AntiPatternDetector
- [ ] Create anti_patterns.json
- [ ] Implement baseline validation
- [ ] Add warning system

### Session 6: Blueprint & Generation
- [ ] Implement StudyBlueprint
- [ ] Blueprint generation and review
- [ ] What-if modifications
- [ ] Integrate with StudyWizard
- [ ] Generate INTERVIEW_LOG.md

### Session 7: Polish
- [ ] Update OP_01 protocol
- [ ] Error handling
- [ ] Unit tests
- [ ] Integration tests
- [ ] Documentation

---

## 13. Success Metrics

| Metric | Target |
|--------|--------|
| Interview completion rate | >90% |
| First-run study success | >95% |
| Time to complete (simple) | <5 min |
| Anti-patterns caught | 100% |
| Resume success rate | 100% |

---

*Plan created: 2025-01-02*
*Ready for implementation in Claude Code VS Code Extension*