2026-01-03 11:06:07 -05:00
# 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 |
|-----------|----------------|
2026-01-20 10:03:45 -05:00
| **Conversational interface ** | Natural conversation, not forms |
2026-01-03 11:06:07 -05:00
| **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*
