# 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 | |-----------|----------------| | **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*