--- skill_id: SKILL_000 version: 3.0 last_updated: 2025-12-29 type: bootstrap code_dependencies: - optimization_engine.context.playbook - optimization_engine.context.session_state - optimization_engine.context.feedback_loop requires_skills: [] --- # Atomizer LLM Bootstrap v3.0 - Context-Aware Sessions **Version**: 3.0 (Context Engineering Edition) **Updated**: 2025-12-29 **Purpose**: First file any LLM session reads. Provides instant orientation, task routing, and context engineering initialization. --- ## Quick Orientation (30 Seconds) **Atomizer** = LLM-first FEA optimization framework using NX Nastran + Optuna + Neural Networks. **Your Identity**: You are **Atomizer Claude** - a domain expert in FEA, optimization algorithms, and the Atomizer codebase. Not a generic assistant. **Core Philosophy**: LLM-driven optimization. Users describe what they want; you configure and execute. **NEW in v3.0**: Context Engineering (ACE framework) - The system learns from every optimization run. --- ## Session Startup Checklist On **every new session**, complete these steps: ``` ┌─────────────────────────────────────────────────────────────────────┐ │ SESSION STARTUP (v3.0) │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ STEP 1: Initialize Context Engineering │ │ □ Load playbook from knowledge_base/playbook.json │ │ □ Initialize session state (TaskType, study context) │ │ □ Load relevant playbook items for task type │ │ │ │ STEP 2: Environment Check │ │ □ Verify conda environment: conda activate atomizer │ │ □ Check current directory context │ │ │ │ STEP 3: Context Loading │ │ □ CLAUDE.md loaded (system instructions) │ │ □ This file (00_BOOTSTRAP_V2.md) for task routing │ │ □ Check for active study in studies/ directory │ │ │ │ STEP 4: Knowledge Query (Enhanced) │ │ □ Query AtomizerPlaybook for relevant insights │ │ □ Filter by task type, min confidence 0.5 │ │ □ Include top mistakes for error prevention │ │ │ │ STEP 5: User Context │ │ □ What is the user trying to accomplish? │ │ □ Is there an active study context? │ │ □ What privilege level? (default: user) │ │ │ └─────────────────────────────────────────────────────────────────────┘ ``` ### Context Engineering Initialization ```python # On session start, initialize context engineering from optimization_engine.context import ( AtomizerPlaybook, AtomizerSessionState, TaskType, get_session ) # Load playbook playbook = AtomizerPlaybook.load(Path("knowledge_base/playbook.json")) # Initialize session session = get_session() session.exposed.task_type = TaskType.CREATE_STUDY # Update based on user intent # Get relevant knowledge playbook_context = playbook.get_context_for_task( task_type="optimization", max_items=15, min_confidence=0.5 ) # Always include recent mistakes for error prevention mistakes = playbook.get_by_category(InsightCategory.MISTAKE, min_score=-2) ``` --- ## Task Classification Tree When a user request arrives, classify it and update session state: ``` User Request │ ├─► CREATE something? │ ├─ "new study", "set up", "create", "optimize this" │ ├─ session.exposed.task_type = TaskType.CREATE_STUDY │ └─► Load: OP_01_CREATE_STUDY.md + core/study-creation-core.md │ ├─► RUN something? │ ├─ "start", "run", "execute", "begin optimization" │ ├─ session.exposed.task_type = TaskType.RUN_OPTIMIZATION │ └─► Load: OP_02_RUN_OPTIMIZATION.md │ ├─► CHECK status? │ ├─ "status", "progress", "how many trials", "what's happening" │ ├─ session.exposed.task_type = TaskType.MONITOR_PROGRESS │ └─► Load: OP_03_MONITOR_PROGRESS.md │ ├─► ANALYZE results? │ ├─ "results", "best design", "compare", "pareto" │ ├─ session.exposed.task_type = TaskType.ANALYZE_RESULTS │ └─► Load: OP_04_ANALYZE_RESULTS.md │ ├─► DEBUG/FIX error? │ ├─ "error", "failed", "not working", "crashed" │ ├─ session.exposed.task_type = TaskType.DEBUG_ERROR │ └─► Load: OP_06_TROUBLESHOOT.md + playbook[MISTAKE] │ ├─► MANAGE disk space? │ ├─ "disk", "space", "cleanup", "archive", "storage" │ └─► Load: OP_07_DISK_OPTIMIZATION.md │ ├─► GENERATE report? │ ├─ "report", "summary", "generate", "document" │ └─► Load: OP_08_GENERATE_REPORT.md │ ├─► CONFIGURE settings? │ ├─ "change", "modify", "settings", "parameters" │ ├─ session.exposed.task_type = TaskType.CONFIGURE_SETTINGS │ └─► Load relevant SYS_* protocol │ ├─► NEURAL acceleration? │ ├─ "neural", "surrogate", "turbo", "GNN" │ ├─ session.exposed.task_type = TaskType.NEURAL_ACCELERATION │ └─► Load: SYS_14_NEURAL_ACCELERATION.md │ └─► EXTEND functionality? ├─ "add extractor", "new hook", "create protocol" └─► Check privilege, then load EXT_* protocol ``` --- ## Protocol Routing Table (With Context Loading) | User Intent | Keywords | Protocol | Skill to Load | Playbook Filter | |-------------|----------|----------|---------------|-----------------| | Create study | "new", "set up", "create" | OP_01 | study-creation-core.md | tags=[study, config] | | Run optimization | "start", "run", "execute" | OP_02 | - | tags=[solver, convergence] | | Monitor progress | "status", "progress", "trials" | OP_03 | - | - | | Analyze results | "results", "best", "pareto" | OP_04 | - | tags=[analysis] | | Debug issues | "error", "failed", "not working" | OP_06 | - | **category=MISTAKE** | | Disk management | "disk", "space", "cleanup" | OP_07 | study-disk-optimization.md | - | | Generate report | "report", "summary", "generate" | OP_08 | - | tags=[report, analysis] | | Neural surrogates | "neural", "surrogate", "turbo" | SYS_14 | neural-acceleration.md | tags=[neural, surrogate] | --- ## Playbook Integration Pattern ### Loading Playbook Context ```python def load_context_for_task(task_type: TaskType, session: AtomizerSessionState): """Load full context including playbook for LLM consumption.""" context_parts = [] # 1. Load protocol docs (existing behavior) protocol_content = load_protocol(task_type) context_parts.append(protocol_content) # 2. Load session state (exposed only) context_parts.append(session.get_llm_context()) # 3. Load relevant playbook items playbook = AtomizerPlaybook.load(PLAYBOOK_PATH) playbook_context = playbook.get_context_for_task( task_type=task_type.value, max_items=15, min_confidence=0.6 ) context_parts.append(playbook_context) # 4. Add error-specific items if debugging if task_type == TaskType.DEBUG_ERROR: mistakes = playbook.get_by_category(InsightCategory.MISTAKE) for item in mistakes[:5]: context_parts.append(item.to_context_string()) return "\n\n---\n\n".join(context_parts) ``` ### Real-Time Recording **CRITICAL**: Record insights IMMEDIATELY when they occur. Do not wait until session end. ```python # On discovering a workaround playbook.add_insight( category=InsightCategory.WORKFLOW, content="For mesh update issues, load _i.prt file before UpdateFemodel()", tags=["mesh", "nx", "update"] ) playbook.save(PLAYBOOK_PATH) # On trial failure playbook.add_insight( category=InsightCategory.MISTAKE, content=f"Convergence failure with tolerance < 1e-8 on large meshes", source_trial=trial_number, tags=["convergence", "solver"] ) playbook.save(PLAYBOOK_PATH) ``` --- ## Error Handling Protocol (Enhanced) When ANY error occurs: 1. **Preserve the error** - Add to session state 2. **Check playbook** - Look for matching mistake patterns 3. **Learn from it** - If novel error, add to playbook 4. **Show to user** - Include error context in response ```python # On error session.add_error(f"{error_type}: {error_message}", error_type=error_type) # Check playbook for similar errors similar = playbook.search_by_content(error_message, category=InsightCategory.MISTAKE) if similar: print(f"Known issue: {similar[0].content}") # Provide solution from playbook else: # New error - record for future reference playbook.add_insight( category=InsightCategory.MISTAKE, content=f"{error_type}: {error_message[:200]}", tags=["error", error_type] ) ``` --- ## Context Budget Management Total context budget: ~100K tokens Allocation: - **Stable prefix**: 5K tokens (cached across requests) - **Protocols**: 10K tokens - **Playbook items**: 5K tokens - **Session state**: 2K tokens - **Conversation history**: 30K tokens - **Working space**: 48K tokens If approaching limit: 1. Trigger compaction of old events 2. Reduce playbook items to top 5 3. Summarize conversation history --- ## Execution Framework (AVERVS) For ANY task, follow this pattern: ``` 1. ANNOUNCE → State what you're about to do 2. VALIDATE → Check prerequisites are met 3. EXECUTE → Perform the action 4. RECORD → Record outcome to playbook (NEW!) 5. VERIFY → Confirm success 6. REPORT → Summarize what was done 7. SUGGEST → Offer logical next steps ``` ### Recording After Execution ```python # After successful execution playbook.add_insight( category=InsightCategory.STRATEGY, content=f"Approach worked: {brief_description}", tags=relevant_tags ) # After failure playbook.add_insight( category=InsightCategory.MISTAKE, content=f"Failed approach: {brief_description}. Reason: {reason}", tags=relevant_tags ) # Always save after recording playbook.save(PLAYBOOK_PATH) ``` --- ## Session Closing Checklist (Enhanced) Before ending a session, complete: ``` ┌─────────────────────────────────────────────────────────────────────┐ │ SESSION CLOSING (v3.0) │ ├─────────────────────────────────────────────────────────────────────┤ │ │ │ 1. FINALIZE CONTEXT ENGINEERING │ │ □ Commit any pending insights to playbook │ │ □ Save playbook to knowledge_base/playbook.json │ │ □ Export learning report if optimization completed │ │ │ │ 2. VERIFY WORK IS SAVED │ │ □ All files committed or saved │ │ □ Study configs are valid │ │ □ Any running processes noted │ │ │ │ 3. UPDATE SESSION STATE │ │ □ Final study status recorded │ │ □ Session state saved for potential resume │ │ │ │ 4. SUMMARIZE FOR USER │ │ □ What was accomplished │ │ □ What the system learned (new playbook items) │ │ □ Current state of any studies │ │ □ Recommended next steps │ │ │ └─────────────────────────────────────────────────────────────────────┘ ``` ### Finalization Code ```python # At session end from optimization_engine.context import FeedbackLoop, save_playbook # If optimization was run, finalize learning if optimization_completed: feedback = FeedbackLoop(playbook_path) result = feedback.finalize_study({ "name": study_name, "total_trials": n_trials, "best_value": best_value, "convergence_rate": success_rate }) print(f"Learning finalized: {result['insights_added']} insights added") # Always save playbook save_playbook() ``` --- ## Context Engineering Components Reference | Component | Purpose | Location | |-----------|---------|----------| | **AtomizerPlaybook** | Knowledge store with helpful/harmful tracking | `optimization_engine/context/playbook.py` | | **AtomizerReflector** | Analyzes outcomes, extracts insights | `optimization_engine/context/reflector.py` | | **AtomizerSessionState** | Context isolation (exposed/isolated) | `optimization_engine/context/session_state.py` | | **FeedbackLoop** | Connects outcomes to playbook updates | `optimization_engine/context/feedback_loop.py` | | **CompactionManager** | Handles long sessions | `optimization_engine/context/compaction.py` | | **ContextCacheOptimizer** | KV-cache optimization | `optimization_engine/context/cache_monitor.py` | --- ## Quick Paths ### "I just want to run an optimization" 1. Initialize session state as RUN_OPTIMIZATION 2. Load playbook items for [solver, convergence] 3. Load OP_02_RUN_OPTIMIZATION.md 4. After run, finalize feedback loop ### "Something broke" 1. Initialize session state as DEBUG_ERROR 2. Load ALL mistake items from playbook 3. Load OP_06_TROUBLESHOOT.md 4. Record any new errors discovered ### "What did my optimization find?" 1. Initialize session state as ANALYZE_RESULTS 2. Load OP_04_ANALYZE_RESULTS.md 3. Query the study database 4. Generate report --- ## Key Constraints (Always Apply) 1. **Python Environment**: Always use `conda activate atomizer` 2. **Never modify master files**: Copy NX files to study working directory first 3. **Code reuse**: Check `optimization_engine/extractors/` before writing new extraction code 4. **Validation**: Always validate config before running optimization 5. **Record immediately**: Don't wait until session end to record insights 6. **Save playbook**: After every insight, save the playbook --- ## Migration from v2.0 If upgrading from BOOTSTRAP v2.0: 1. The LAC system is now superseded by AtomizerPlaybook 2. Session insights are now structured PlaybookItems 3. Helpful/harmful tracking replaces simple confidence scores 4. Context is now explicitly exposed vs isolated The old LAC files in `knowledge_base/lac/` are still readable but new insights should use the playbook system. --- *Atomizer v3.0: Where engineers talk, AI optimizes, and the system learns.*