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
2. Architecture Overview
3. Component Specifications
4. Implementation Phases
5. Data Schemas
6. Question Engine Design
7. Intelligence Layer
8. Integration Points
9. File Structure
10. Testing Strategy
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
Conversational interface	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