Antoine/Atomizer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Consolidate documentation and fix protocol numbering (partial)

Browse Source 
Phase 2 of restructuring plan:
- Rename SYS_16_STUDY_INSIGHTS -> SYS_17_STUDY_INSIGHTS
- Rename SYS_17_CONTEXT_ENGINEERING -> SYS_18_CONTEXT_ENGINEERING
- Promote Bootstrap V3.0 (Context Engineering) as default
- Archive old Bootstrap V2.0
- Create knowledge_base/playbook.json for ACE framework
- Add OP_08 (Generate Report) to routing tables
- Add SYS_16-18 to protocol tables
- Update docs/protocols/README.md to version 1.1
- Update CLAUDE.md with new protocols
- Create docs/plans/RESTRUCTURING_PLAN.md for continuation

Remaining: Phase 2.8 (Cheatsheet), Phases 3-6

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Anto01
2026-01-07 08:52:07 -05:00
parent 18c221a218
commit b8a04c62b8
17 changed files with 1568 additions and 623 deletions
Download Patch File Download Diff File Expand all files Collapse all files

483
.claude/skills/00_BOOTSTRAP.md
View File

@@ -1,17 +1,20 @@
---
skill_id: SKILL_000
version: 2.0
last_updated: 2025-12-07
version: 3.0
last_updated: 2025-12-29
type: bootstrap
code_dependencies: []
code_dependencies:
- optimization_engine.context.playbook
- optimization_engine.context.session_state
- optimization_engine.context.feedback_loop
requires_skills: []
---
# Atomizer LLM Bootstrap
# Atomizer LLM Bootstrap v3.0 - Context-Aware Sessions
**Version**: 2.0
**Updated**: 2025-12-07
**Purpose**: First file any LLM session reads. Provides instant orientation and task routing.
**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.
---
@@ -23,6 +26,8 @@ requires_skills: []
**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
@@ -31,23 +36,29 @@ On **every new session**, complete these steps:
```
┌─────────────────────────────────────────────────────────────────────┐
│ SESSION STARTUP │
│ SESSION STARTUP (v3.0) │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ STEP 1: Environment Check │
│ 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 2: Context Loading │
│ STEP 3: Context Loading │
│ □ CLAUDE.md loaded (system instructions) │
│ □ This file (00_BOOTSTRAP.md) for task routing │
│ □ This file (00_BOOTSTRAP_V2.md) for task routing │
│ □ Check for active study in studies/ directory │
│ │
│ STEP 3: Knowledge Query (LAC) │
│ □ Query knowledge_base/lac/ for relevant prior learnings │
│ □ Note any pending protocol updates │
│ 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 4: User Context │
│ STEP 5: User Context │
│ □ What is the user trying to accomplish? │
│ □ Is there an active study context? │
│ □ What privilege level? (default: user) │
@@ -55,127 +66,217 @@ On **every new session**, complete these steps:
└─────────────────────────────────────────────────────────────────────┘
```
### 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:
When a user request arrives, classify it and update session state:
```
User Request
│
├─► CREATE something?
│ ├─ "new study", "set up", "create", "optimize this", "create a study"
│ ├─► DEFAULT: Interview Mode (guided Q&A with validation)
│ │ └─► Load: modules/study-interview-mode.md + OP_01
│ │
│ └─► MANUAL mode? (power users, explicit request)
│ ├─ "quick setup", "skip interview", "manual config"
│ └─► Load: OP_01_CREATE_STUDY.md + core/study-creation-core.md
│ ├─ "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"
│ └─► Load: OP_06_TROUBLESHOOT.md
│ ├─ 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
│
├─► EXTEND functionality?
│ ├─ "add extractor", "new hook", "create protocol"
│ └─► Check privilege, then load EXT_* protocol
├─► NEURAL acceleration?
│ ├─ "neural", "surrogate", "turbo", "GNN"
│ ├─ session.exposed.task_type = TaskType.NEURAL_ACCELERATION
│ └─► Load: SYS_14_NEURAL_ACCELERATION.md
│
└─► EXPLAIN/LEARN?
├─ "what is", "how does", "explain"
└─► Load relevant SYS_* protocol for reference
└─► EXTEND functionality?
├─ "add extractor", "new hook", "create protocol"
└─► Check privilege, then load EXT_* protocol
```
---
## Protocol Routing Table
## Protocol Routing Table (With Context Loading)
| User Intent | Keywords | Protocol | Skill to Load | Privilege |
|-------------|----------|----------|---------------|-----------|
| **Create study (DEFAULT)** | "new", "set up", "create", "optimize", "create a study" | OP_01 | **modules/study-interview-mode.md** | user |
| Create study (manual) | "quick setup", "skip interview", "manual config" | OP_01 | core/study-creation-core.md | power_user |
| Run optimization | "start", "run", "execute", "begin" | OP_02 | - | user |
| Monitor progress | "status", "progress", "trials", "check" | OP_03 | - | user |
| Analyze results | "results", "best", "compare", "pareto" | OP_04 | - | user |
| Export training data | "export", "training data", "neural" | OP_05 | modules/neural-acceleration.md | user |
| Debug issues | "error", "failed", "not working", "help" | OP_06 | - | user |
| **Disk management** | "disk", "space", "cleanup", "archive" | **OP_07** | modules/study-disk-optimization.md | user |
| Understand IMSO | "protocol 10", "IMSO", "adaptive" | SYS_10 | - | user |
| Multi-objective | "pareto", "NSGA", "multi-objective" | SYS_11 | - | user |
| Extractors | "extractor", "displacement", "stress" | SYS_12 | modules/extractors-catalog.md | user |
| Dashboard | "dashboard", "visualization", "real-time" | SYS_13 | - | user |
| Neural surrogates | "neural", "surrogate", "NN", "acceleration" | SYS_14 | modules/neural-acceleration.md | user |
| Add extractor | "create extractor", "new physics" | EXT_01 | - | power_user |
| Add hook | "create hook", "lifecycle", "callback" | EXT_02 | - | power_user |
| Add protocol | "create protocol", "new protocol" | EXT_03 | - | admin |
| Add skill | "create skill", "new skill" | EXT_04 | - | admin |
| 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] |
---
## Role Detection
## Playbook Integration Pattern
Determine user's privilege level:
### Loading Playbook Context
| Role | How to Detect | Can Do | Cannot Do |
|------|---------------|--------|-----------|
| **user** | Default for all sessions | Run studies, monitor, analyze, configure | Create extractors, modify protocols |
| **power_user** | User states they're a developer, or session context indicates | Create extractors, add hooks | Create protocols, modify skills |
| **admin** | Explicit declaration, admin config present | Full access | - |
```python
def load_context_for_task(task_type: TaskType, session: AtomizerSessionState):
"""Load full context including playbook for LLM consumption."""
context_parts = []
**Default**: Assume `user` unless explicitly told otherwise.
# 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())
## Context Loading Rules
# 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)
After classifying the task, load context in this order:
# 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())
### 1. Always Loaded (via CLAUDE.md)
- This file (00_BOOTSTRAP.md)
- Python environment rules
- Code reuse protocol
### 2. Load Per Task Type
See `02_CONTEXT_LOADER.md` for complete loading rules.
**Quick Reference**:
return "\n\n---\n\n".join(context_parts)
```
CREATE_STUDY → core/study-creation-core.md (PRIMARY)
→ SYS_12_EXTRACTOR_LIBRARY.md (extractor reference)
→ modules/zernike-optimization.md (if telescope/mirror)
→ modules/neural-acceleration.md (if >50 trials)
RUN_OPTIMIZATION → OP_02_RUN_OPTIMIZATION.md
→ SYS_15_METHOD_SELECTOR.md (method recommendation)
→ SYS_14_NEURAL_ACCELERATION.md (if neural/turbo)
### Real-Time Recording
DEBUG → OP_06_TROUBLESHOOT.md
→ Relevant SYS_* based on error type
**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)
```
---
## Execution Framework
## 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:
@@ -183,60 +284,122 @@ 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. VERIFY → Confirm success
5. REPORT → Summarize what was done
6. SUGGEST → Offer logical next steps
4. RECORD → Record outcome to playbook (NEW!)
5. VERIFY → Confirm success
6. REPORT → Summarize what was done
7. SUGGEST → Offer logical next steps
```
See `PROTOCOL_EXECUTION.md` for detailed execution rules.
### 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)
```
---
## Emergency Quick Paths
## 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. Do you have a `.prt` and `.sim` file? → Yes: OP_01 → OP_02
2. Getting errors? → OP_06
3. Want to see progress? → OP_03
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. Read the error message
2. Load OP_06_TROUBLESHOOT.md
3. Follow diagnostic flowchart
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. Load OP_04_ANALYZE_RESULTS.md
2. Query the study database
3. Generate report
---
## Protocol Directory Map
```
docs/protocols/
├── operations/ # Layer 2: How-to guides
│ ├── OP_01_CREATE_STUDY.md
│ ├── OP_02_RUN_OPTIMIZATION.md
│ ├── OP_03_MONITOR_PROGRESS.md
│ ├── OP_04_ANALYZE_RESULTS.md
│ ├── OP_05_EXPORT_TRAINING_DATA.md
│ └── OP_06_TROUBLESHOOT.md
│
├── system/ # Layer 3: Core specifications
│ ├── SYS_10_IMSO.md
│ ├── SYS_11_MULTI_OBJECTIVE.md
│ ├── SYS_12_EXTRACTOR_LIBRARY.md
│ ├── SYS_13_DASHBOARD_TRACKING.md
│ └── SYS_14_NEURAL_ACCELERATION.md
│
└── extensions/ # Layer 4: Extensibility guides
├── EXT_01_CREATE_EXTRACTOR.md
├── EXT_02_CREATE_HOOK.md
├── EXT_03_CREATE_PROTOCOL.md
├── EXT_04_CREATE_SKILL.md
└── templates/
```
1. Initialize session state as ANALYZE_RESULTS
2. Load OP_04_ANALYZE_RESULTS.md
3. Query the study database
4. Generate report
---
@@ -246,72 +409,22 @@ docs/protocols/
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. **Documentation**: Every study needs README.md and STUDY_REPORT.md
5. **Record immediately**: Don't wait until session end to record insights
6. **Save playbook**: After every insight, save the playbook
---
## Next Steps After Bootstrap
## Migration from v2.0
1. If you know the task type → Go to relevant OP_* or SYS_* protocol
2. If unclear → Ask user clarifying question
3. If complex task → Read `01_CHEATSHEET.md` for quick reference
4. If need detailed loading rules → Read `02_CONTEXT_LOADER.md`
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.
---
## Session Closing Checklist
Before ending a session, complete:
```
┌─────────────────────────────────────────────────────────────────────┐
│ SESSION CLOSING │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 1. VERIFY WORK IS SAVED │
│ □ All files committed or saved │
│ □ Study configs are valid │
│ □ Any running processes noted │
│ │
│ 2. RECORD LEARNINGS TO LAC │
│ □ Any failures and their solutions → failure.jsonl │
│ □ Success patterns discovered → success_pattern.jsonl │
│ □ User preferences noted → user_preference.jsonl │
│ □ Protocol improvements → suggested_updates.jsonl │
│ │
│ 3. RECORD OPTIMIZATION OUTCOMES │
│ □ If optimization completed, record to optimization_memory/ │
│ □ Include: method, geometry_type, converged, convergence_trial │
│ │
│ 4. SUMMARIZE FOR USER │
│ □ What was accomplished │
│ □ Current state of any studies │
│ □ Recommended next steps │
│ │
└─────────────────────────────────────────────────────────────────────┘
```
### Session Summary Template
```markdown
# Session Summary
**Date**: {YYYY-MM-DD}
**Study Context**: {study_name or "General"}
## Accomplished
- {task 1}
- {task 2}
## Current State
- Study: {status}
- Trials: {N completed}
- Next action needed: {action}
## Learnings Recorded
- {insight 1}
## Recommended Next Steps
1. {step 1}
2. {step 2}
```
*Atomizer v3.0: Where engineers talk, AI optimizes, and the system learns.*

425
.claude/skills/00_BOOTSTRAP_V2.md
View File

@@ -1,425 +0,0 @@
---
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
│
├─► 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 | - |
| 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.*

2
.claude/skills/01_CHEATSHEET.md
View File

@@ -671,4 +671,4 @@ feedback.process_trial_result(
|---------|-----|---------|
| Context API | `http://localhost:5000/api/context` | Playbook management |
**Full documentation**: `docs/protocols/system/SYS_17_CONTEXT_ENGINEERING.md`
**Full documentation**: `docs/protocols/system/SYS_18_CONTEXT_ENGINEERING.md`

317
.claude/skills/archive/00_BOOTSTRAP_V2.0_archived.md Normal file
View File

@@ -0,0 +1,317 @@
---
skill_id: SKILL_000
version: 2.0
last_updated: 2025-12-07
type: bootstrap
code_dependencies: []
requires_skills: []
---
# Atomizer LLM Bootstrap
**Version**: 2.0
**Updated**: 2025-12-07
**Purpose**: First file any LLM session reads. Provides instant orientation and task routing.
---
## 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.
---
## Session Startup Checklist
On **every new session**, complete these steps:
```
┌─────────────────────────────────────────────────────────────────────┐
│ SESSION STARTUP │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ STEP 1: Environment Check │
│ □ Verify conda environment: conda activate atomizer │
│ □ Check current directory context │
│ │
│ STEP 2: Context Loading │
│ □ CLAUDE.md loaded (system instructions) │
│ □ This file (00_BOOTSTRAP.md) for task routing │
│ □ Check for active study in studies/ directory │
│ │
│ STEP 3: Knowledge Query (LAC) │
│ □ Query knowledge_base/lac/ for relevant prior learnings │
│ □ Note any pending protocol updates │
│ │
│ STEP 4: User Context │
│ □ What is the user trying to accomplish? │
│ □ Is there an active study context? │
│ □ What privilege level? (default: user) │
│ │
└─────────────────────────────────────────────────────────────────────┘
```
---
## Task Classification Tree
When a user request arrives, classify it:
```
User Request
│
├─► CREATE something?
│ ├─ "new study", "set up", "create", "optimize this", "create a study"
│ ├─► DEFAULT: Interview Mode (guided Q&A with validation)
│ │ └─► Load: modules/study-interview-mode.md + OP_01
│ │
│ └─► MANUAL mode? (power users, explicit request)
│ ├─ "quick setup", "skip interview", "manual config"
│ └─► Load: OP_01_CREATE_STUDY.md + core/study-creation-core.md
│
├─► RUN something?
│ ├─ "start", "run", "execute", "begin optimization"
│ └─► Load: OP_02_RUN_OPTIMIZATION.md
│
├─► CHECK status?
│ ├─ "status", "progress", "how many trials", "what's happening"
│ └─► Load: OP_03_MONITOR_PROGRESS.md
│
├─► ANALYZE results?
│ ├─ "results", "best design", "compare", "pareto"
│ └─► Load: OP_04_ANALYZE_RESULTS.md
│
├─► DEBUG/FIX error?
│ ├─ "error", "failed", "not working", "crashed"
│ └─► Load: OP_06_TROUBLESHOOT.md
│
├─► MANAGE disk space?
│ ├─ "disk", "space", "cleanup", "archive", "storage"
│ └─► Load: OP_07_DISK_OPTIMIZATION.md
│
├─► CONFIGURE settings?
│ ├─ "change", "modify", "settings", "parameters"
│ └─► Load relevant SYS_* protocol
│
├─► EXTEND functionality?
│ ├─ "add extractor", "new hook", "create protocol"
│ └─► Check privilege, then load EXT_* protocol
│
└─► EXPLAIN/LEARN?
├─ "what is", "how does", "explain"
└─► Load relevant SYS_* protocol for reference
```
---
## Protocol Routing Table
| User Intent | Keywords | Protocol | Skill to Load | Privilege |
|-------------|----------|----------|---------------|-----------|
| **Create study (DEFAULT)** | "new", "set up", "create", "optimize", "create a study" | OP_01 | **modules/study-interview-mode.md** | user |
| Create study (manual) | "quick setup", "skip interview", "manual config" | OP_01 | core/study-creation-core.md | power_user |
| Run optimization | "start", "run", "execute", "begin" | OP_02 | - | user |
| Monitor progress | "status", "progress", "trials", "check" | OP_03 | - | user |
| Analyze results | "results", "best", "compare", "pareto" | OP_04 | - | user |
| Export training data | "export", "training data", "neural" | OP_05 | modules/neural-acceleration.md | user |
| Debug issues | "error", "failed", "not working", "help" | OP_06 | - | user |
| **Disk management** | "disk", "space", "cleanup", "archive" | **OP_07** | modules/study-disk-optimization.md | user |
| Understand IMSO | "protocol 10", "IMSO", "adaptive" | SYS_10 | - | user |
| Multi-objective | "pareto", "NSGA", "multi-objective" | SYS_11 | - | user |
| Extractors | "extractor", "displacement", "stress" | SYS_12 | modules/extractors-catalog.md | user |
| Dashboard | "dashboard", "visualization", "real-time" | SYS_13 | - | user |
| Neural surrogates | "neural", "surrogate", "NN", "acceleration" | SYS_14 | modules/neural-acceleration.md | user |
| Add extractor | "create extractor", "new physics" | EXT_01 | - | power_user |
| Add hook | "create hook", "lifecycle", "callback" | EXT_02 | - | power_user |
| Add protocol | "create protocol", "new protocol" | EXT_03 | - | admin |
| Add skill | "create skill", "new skill" | EXT_04 | - | admin |
---
## Role Detection
Determine user's privilege level:
| Role | How to Detect | Can Do | Cannot Do |
|------|---------------|--------|-----------|
| **user** | Default for all sessions | Run studies, monitor, analyze, configure | Create extractors, modify protocols |
| **power_user** | User states they're a developer, or session context indicates | Create extractors, add hooks | Create protocols, modify skills |
| **admin** | Explicit declaration, admin config present | Full access | - |
**Default**: Assume `user` unless explicitly told otherwise.
---
## Context Loading Rules
After classifying the task, load context in this order:
### 1. Always Loaded (via CLAUDE.md)
- This file (00_BOOTSTRAP.md)
- Python environment rules
- Code reuse protocol
### 2. Load Per Task Type
See `02_CONTEXT_LOADER.md` for complete loading rules.
**Quick Reference**:
```
CREATE_STUDY → core/study-creation-core.md (PRIMARY)
→ SYS_12_EXTRACTOR_LIBRARY.md (extractor reference)
→ modules/zernike-optimization.md (if telescope/mirror)
→ modules/neural-acceleration.md (if >50 trials)
RUN_OPTIMIZATION → OP_02_RUN_OPTIMIZATION.md
→ SYS_15_METHOD_SELECTOR.md (method recommendation)
→ SYS_14_NEURAL_ACCELERATION.md (if neural/turbo)
DEBUG → OP_06_TROUBLESHOOT.md
→ Relevant SYS_* based on error type
```
---
## Execution Framework
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. VERIFY → Confirm success
5. REPORT → Summarize what was done
6. SUGGEST → Offer logical next steps
```
See `PROTOCOL_EXECUTION.md` for detailed execution rules.
---
## Emergency Quick Paths
### "I just want to run an optimization"
1. Do you have a `.prt` and `.sim` file? → Yes: OP_01 → OP_02
2. Getting errors? → OP_06
3. Want to see progress? → OP_03
### "Something broke"
1. Read the error message
2. Load OP_06_TROUBLESHOOT.md
3. Follow diagnostic flowchart
### "What did my optimization find?"
1. Load OP_04_ANALYZE_RESULTS.md
2. Query the study database
3. Generate report
---
## Protocol Directory Map
```
docs/protocols/
├── operations/ # Layer 2: How-to guides
│ ├── OP_01_CREATE_STUDY.md
│ ├── OP_02_RUN_OPTIMIZATION.md
│ ├── OP_03_MONITOR_PROGRESS.md
│ ├── OP_04_ANALYZE_RESULTS.md
│ ├── OP_05_EXPORT_TRAINING_DATA.md
│ └── OP_06_TROUBLESHOOT.md
│
├── system/ # Layer 3: Core specifications
│ ├── SYS_10_IMSO.md
│ ├── SYS_11_MULTI_OBJECTIVE.md
│ ├── SYS_12_EXTRACTOR_LIBRARY.md
│ ├── SYS_13_DASHBOARD_TRACKING.md
│ └── SYS_14_NEURAL_ACCELERATION.md
│
└── extensions/ # Layer 4: Extensibility guides
├── EXT_01_CREATE_EXTRACTOR.md
├── EXT_02_CREATE_HOOK.md
├── EXT_03_CREATE_PROTOCOL.md
├── EXT_04_CREATE_SKILL.md
└── templates/
```
---
## 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. **Documentation**: Every study needs README.md and STUDY_REPORT.md
---
## Next Steps After Bootstrap
1. If you know the task type → Go to relevant OP_* or SYS_* protocol
2. If unclear → Ask user clarifying question
3. If complex task → Read `01_CHEATSHEET.md` for quick reference
4. If need detailed loading rules → Read `02_CONTEXT_LOADER.md`
---
## Session Closing Checklist
Before ending a session, complete:
```
┌─────────────────────────────────────────────────────────────────────┐
│ SESSION CLOSING │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ 1. VERIFY WORK IS SAVED │
│ □ All files committed or saved │
│ □ Study configs are valid │
│ □ Any running processes noted │
│ │
│ 2. RECORD LEARNINGS TO LAC │
│ □ Any failures and their solutions → failure.jsonl │
│ □ Success patterns discovered → success_pattern.jsonl │
│ □ User preferences noted → user_preference.jsonl │
│ □ Protocol improvements → suggested_updates.jsonl │
│ │
│ 3. RECORD OPTIMIZATION OUTCOMES │
│ □ If optimization completed, record to optimization_memory/ │
│ □ Include: method, geometry_type, converged, convergence_trial │
│ │
│ 4. SUMMARIZE FOR USER │
│ □ What was accomplished │
│ □ Current state of any studies │
│ □ Recommended next steps │
│ │
└─────────────────────────────────────────────────────────────────────┘
```
### Session Summary Template
```markdown
# Session Summary
**Date**: {YYYY-MM-DD}
**Study Context**: {study_name or "General"}
## Accomplished
- {task 1}
- {task 2}
## Current State
- Study: {status}
- Trials: {N completed}
- Next action needed: {action}
## Learnings Recorded
- {insight 1}
## Recommended Next Steps
1. {step 1}
2. {step 2}
```

2
.claude/skills/modules/OPTIMIZATION_ENGINE_MIGRATION_PLAN.md
View File

@@ -497,7 +497,7 @@ docs/protocols/system/SYS_12_EXTRACTOR_LIBRARY.md (lines 71-851 - MANY reference
docs/protocols/system/SYS_13_DASHBOARD_TRACKING.md (lines 60, 85, 315)
docs/protocols/system/SYS_14_NEURAL_ACCELERATION.md (lines 231-1080)
docs/protocols/system/SYS_15_METHOD_SELECTOR.md (lines 42-422)
docs/protocols/system/SYS_16_STUDY_INSIGHTS.md (lines 62-498)
docs/protocols/system/SYS_17_STUDY_INSIGHTS.md (lines 62-498)
docs/protocols/extensions/EXT_01_CREATE_EXTRACTOR.md (lines 35-287)
docs/protocols/extensions/EXT_02_CREATE_HOOK.md (lines 45-357)
docs/protocols/extensions/EXT_03_CREATE_INSIGHT.md

2
.claude/skills/modules/insights-catalog.md
View File

@@ -283,7 +283,7 @@ python -m optimization_engine.insights recommend studies/my_study
## Related Documentation
- **Protocol Specification**: `docs/protocols/system/SYS_16_STUDY_INSIGHTS.md`
- **Protocol Specification**: `docs/protocols/system/SYS_17_STUDY_INSIGHTS.md`
- **OPD Method Physics**: `docs/06_PHYSICS/ZERNIKE_OPD_METHOD.md`
- **Zernike Integration**: `docs/ZERNIKE_INTEGRATION.md`
- **Extractor Catalog**: `.claude/skills/modules/extractors-catalog.md`