Atomizer/.claude/skills/PROTOCOL_EXECUTION.md

# Protocol Execution Framework (PEF)

**Version**: 1.0
**Purpose**: Meta-protocol defining how LLM sessions execute Atomizer protocols. The "protocol for using protocols."

---

## Core Execution Pattern

For ANY task, follow this 6-step pattern:

```
┌─────────────────────────────────────────────────────────────┐
│  1. ANNOUNCE                                                 │
│     State what you're about to do in plain language          │
│     "I'll create an optimization study for your bracket..."  │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  2. VALIDATE                                                 │
│     Check prerequisites are met                              │
│     - Required files exist?                                  │
│     - Environment ready?                                     │
│     - User has confirmed understanding?                      │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  3. EXECUTE                                                  │
│     Perform the action following protocol steps              │
│     - Load required context per 02_CONTEXT_LOADER.md         │
│     - Follow protocol step-by-step                           │
│     - Handle errors with OP_06 patterns                      │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  4. VERIFY                                                   │
│     Confirm success                                          │
│     - Files created correctly?                               │
│     - No errors in output?                                   │
│     - Results make sense?                                    │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  5. REPORT                                                   │
│     Summarize what was done                                  │
│     - List files created/modified                            │
│     - Show key results                                       │
│     - Note any warnings                                      │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  6. SUGGEST                                                  │
│     Offer logical next steps                                 │
│     - What should user do next?                              │
│     - Related operations available?                          │
│     - Dashboard URL if relevant?                             │
└─────────────────────────────────────────────────────────────┘
```

---

## Task Classification Rules

Before executing, classify the user's request:

### Step 1: Identify Task Category

```python
TASK_CATEGORIES = {
    "CREATE": {
        "keywords": ["new", "create", "set up", "optimize", "study", "build"],
        "protocol": "OP_01_CREATE_STUDY",
        "privilege": "user"
    },
    "RUN": {
        "keywords": ["start", "run", "execute", "begin", "launch"],
        "protocol": "OP_02_RUN_OPTIMIZATION",
        "privilege": "user"
    },
    "MONITOR": {
        "keywords": ["status", "progress", "check", "how many", "trials"],
        "protocol": "OP_03_MONITOR_PROGRESS",
        "privilege": "user"
    },
    "ANALYZE": {
        "keywords": ["results", "best", "compare", "pareto", "report"],
        "protocol": "OP_04_ANALYZE_RESULTS",
        "privilege": "user"
    },
    "EXPORT": {
        "keywords": ["export", "training data", "neural data"],
        "protocol": "OP_05_EXPORT_TRAINING_DATA",
        "privilege": "user"
    },
    "DEBUG": {
        "keywords": ["error", "failed", "not working", "crashed", "help"],
        "protocol": "OP_06_TROUBLESHOOT",
        "privilege": "user"
    },
    "EXTEND": {
        "keywords": ["add extractor", "create hook", "new protocol"],
        "protocol": "EXT_*",
        "privilege": "power_user+"
    }
}
```

### Step 2: Check Privilege

```python
def check_privilege(task_category, user_role):
    required = TASK_CATEGORIES[task_category]["privilege"]

    privilege_hierarchy = ["user", "power_user", "admin"]

    if privilege_hierarchy.index(user_role) >= privilege_hierarchy.index(required):
        return True
    else:
        # Inform user they need higher privilege
        return False
```

### Step 3: Load Context

Follow rules in `02_CONTEXT_LOADER.md` to load appropriate documentation.

---

## Validation Checkpoints

Before executing any protocol step, validate:

### Pre-Study Creation
- [ ] Model files exist (`.prt`, `.sim`)
- [ ] Working directory is writable
- [ ] User has described objectives clearly
- [ ] Conda environment is atomizer

### Pre-Run
- [ ] `optimization_config.json` exists and is valid
- [ ] `run_optimization.py` exists
- [ ] Model files copied to `1_setup/model/`
- [ ] No conflicting process running

### Pre-Analysis
- [ ] `study.db` exists with completed trials
- [ ] No optimization currently running

### Pre-Extension (power_user+)
- [ ] User has confirmed their role
- [ ] Extension doesn't duplicate existing functionality
- [ ] Tests can be written for new code

---

## Error Recovery Protocol

When something fails during execution:

### Step 1: Identify Failure Point
```
Which step failed?
├─ File creation?     → Check permissions, disk space
├─ NX solve?          → Check NX log, timeout, expressions
├─ Extraction?        → Check OP2 exists, subcase correct
├─ Database?          → Check SQLite file, trial count
└─ Unknown?           → Capture full error, check OP_06
```

### Step 2: Attempt Recovery

```python
RECOVERY_ACTIONS = {
    "file_permission": "Check directory permissions, try different location",
    "nx_timeout": "Increase timeout in config, simplify model",
    "nx_expression_error": "Verify expression names match NX model",
    "op2_missing": "Check NX solve completed successfully",
    "extractor_error": "Verify correct subcase and element types",
    "database_locked": "Wait for other process to finish, or kill stale process",
}
```

### Step 3: Escalate if Needed

If recovery fails:
1. Log the error with full context
2. Inform user of the issue
3. Suggest manual intervention if appropriate
4. Offer to retry after user fixes underlying issue

---

## Protocol Combination Rules

Some protocols work together, others conflict:

### Valid Combinations
```
OP_01 + SYS_10         # Create study with IMSO
OP_01 + SYS_11         # Create multi-objective study
OP_01 + SYS_14         # Create study with neural acceleration
OP_02 + SYS_13         # Run with dashboard tracking
OP_04 + SYS_11         # Analyze multi-objective results
```

### Invalid Combinations
```
SYS_10 + SYS_11        # Single-obj IMSO with multi-obj NSGA (pick one)
TPESampler + SYS_11    # TPE is single-objective; use NSGAIISampler
EXT_* without privilege # Extensions require power_user or admin
```

### Automatic Protocol Inference
```
If objectives.length == 1:
    → Use Protocol 10 (single-objective)
    → Sampler: TPE, CMA-ES, or GP

If objectives.length > 1:
    → Use Protocol 11 (multi-objective)
    → Sampler: NSGA-II (mandatory)

If n_trials > 50 OR surrogate_settings present:
    → Add Protocol 14 (neural acceleration)
```

---

## Execution Logging

During execution, maintain awareness of:

### Session State
```python
session_state = {
    "current_study": None,           # Active study name
    "loaded_protocols": [],          # Protocols currently loaded
    "completed_steps": [],           # Steps completed this session
    "pending_actions": [],           # Actions waiting for user
    "last_error": None,              # Most recent error if any
}
```

### User Communication
- Always explain what you're doing
- Show progress for long operations
- Warn before destructive actions
- Confirm before expensive operations (many trials)

---

## Confirmation Requirements

Some actions require explicit user confirmation:

### Always Confirm
- [ ] Deleting files or studies
- [ ] Overwriting existing study
- [ ] Running >100 trials
- [ ] Modifying master NX files (FORBIDDEN - but confirm user understands)
- [ ] Creating extension (power_user+)

### Confirm If Uncertain
- [ ] Ambiguous objective (minimize or maximize?)
- [ ] Multiple possible extractors
- [ ] Complex multi-solution setup

### No Confirmation Needed
- [ ] Creating new study in empty directory
- [ ] Running validation checks
- [ ] Reading/analyzing results
- [ ] Checking status

---

## Output Format Standards

When reporting results:

### Study Creation Output
```
Created study: {study_name}

Files generated:
  - studies/{study_name}/1_setup/optimization_config.json
  - studies/{study_name}/run_optimization.py
  - studies/{study_name}/README.md
  - studies/{study_name}/STUDY_REPORT.md

Configuration:
  - Design variables: {count}
  - Objectives: {list}
  - Constraints: {list}
  - Protocol: {protocol}
  - Trials: {n_trials}

Next steps:
  1. Copy your NX files to studies/{study_name}/1_setup/model/
  2. Run: conda activate atomizer && python run_optimization.py
  3. Monitor: http://localhost:3000
```

### Run Status Output
```
Study: {study_name}
Status: {running|completed|failed}
Trials: {completed}/{total}
Best value: {value} ({objective_name})
Elapsed: {time}

Dashboard: http://localhost:3000
```

### Error Output
```
Error: {error_type}
Message: {error_message}
Location: {file}:{line}

Diagnosis:
  {explanation}

Recovery:
  {steps to fix}

Reference: OP_06_TROUBLESHOOT.md
```

---

## Quality Checklist

Before considering any task complete:

### For Study Creation
- [ ] `optimization_config.json` validates successfully
- [ ] `run_optimization.py` has no syntax errors
- [ ] `README.md` has all 11 required sections
- [ ] `STUDY_REPORT.md` template created
- [ ] No code duplication (used extractors from library)

### For Execution
- [ ] Optimization started without errors
- [ ] Dashboard shows real-time updates (if enabled)
- [ ] Trials are progressing

### For Analysis
- [ ] Best result(s) identified
- [ ] Constraints satisfied
- [ ] Report generated if requested

### For Extensions
- [ ] New code added to correct location
- [ ] `__init__.py` updated with exports
- [ ] Documentation updated
- [ ] Tests written (or noted as TODO)