---
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**: "Talk, don't click." 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.*
