# Study README Generator Skill

**Skill ID**: STUDY_README_GENERATOR  
**Version**: 1.0  
**Purpose**: Generate intelligent, context-aware README.md files for optimization studies

## When to Use

This skill is invoked automatically during the study intake workflow when:
1. A study moves from `introspected` to `configured` status
2. User explicitly requests README generation
3. Finalizing a study from the inbox

## Input Context

The README generator receives:

```json
{
  "study_name": "bracket_mass_opt_v1",
  "topic": "Brackets",
  "description": "User's description from intake form",
  "spec": { /* Full AtomizerSpec v2.0 */ },
  "introspection": {
    "expressions": [...],
    "mass_kg": 1.234,
    "solver_type": "NX_Nastran"
  },
  "context_files": {
    "goals.md": "User's goals markdown content",
    "notes.txt": "Any additional notes"
  }
}
```

## Output Format

Generate a README.md with these sections:

### 1. Title & Overview
```markdown
# {Study Name}

**Topic**: {Topic}  
**Created**: {Date}  
**Status**: {Status}

{One paragraph executive summary of the optimization goal}
```

### 2. Engineering Problem
```markdown
## Engineering Problem

{Describe the physical problem being solved}

### Model Description
- **Geometry**: {Describe the part/assembly}
- **Material**: {If known from introspection}
- **Baseline Mass**: {mass_kg} kg

### Loading Conditions
{Describe loads and boundary conditions if available}
```

### 3. Optimization Formulation
```markdown
## Optimization Formulation

### Design Variables ({count})
| Variable | Expression | Range | Units |
|----------|------------|-------|-------|
| {name} | {expr_name} | [{min}, {max}] | {units} |

### Objectives ({count})
| Objective | Direction | Weight | Source |
|-----------|-----------|--------|--------|
| {name} | {direction} | {weight} | {extractor} |

### Constraints ({count})
| Constraint | Condition | Threshold | Type |
|------------|-----------|-----------|------|
| {name} | {operator} | {threshold} | {type} |
```

### 4. Methodology
```markdown
## Methodology

### Algorithm
- **Primary**: {algorithm_type}
- **Max Trials**: {max_trials}
- **Surrogate**: {if enabled}

### Physics Extraction
{Describe extractors used}

### Convergence Criteria
{Describe stopping conditions}
```

### 5. Expected Outcomes
```markdown
## Expected Outcomes

Based on the optimization setup:
- Expected improvement: {estimate if baseline available}
- Key trade-offs: {identify from objectives/constraints}
- Risk factors: {any warnings from validation}
```

## Generation Guidelines

1. **Be Specific**: Use actual values from the spec, not placeholders
2. **Be Concise**: Engineers don't want to read novels
3. **Be Accurate**: Only state facts that can be verified from input
4. **Be Helpful**: Include insights that aid understanding
5. **No Fluff**: Avoid marketing language or excessive praise

## Claude Prompt Template

```
You are generating a README.md for an FEA optimization study. 

CONTEXT:
{json_context}

RULES:
1. Use the actual data provided - never use placeholder values
2. Write in technical engineering language appropriate for structural engineers
3. Keep each section concise but complete
4. If information is missing, note it as "TBD" or skip the section
5. Include physical units wherever applicable
6. Format tables properly with alignment

Generate the README.md content:
```

## Example Output

```markdown
# Bracket Mass Optimization V1

**Topic**: Simple_Bracket  
**Created**: 2026-01-22  
**Status**: Configured

Optimize the mass of a structural L-bracket while maintaining stress below yield and displacement within tolerance.

## Engineering Problem

### Model Description
- **Geometry**: L-shaped mounting bracket with web and flange
- **Material**: Steel (assumed based on typical applications)
- **Baseline Mass**: 0.847 kg

### Loading Conditions
Static loading with force applied at mounting holes. Fixed constraints at base.

## Optimization Formulation

### Design Variables (3)
| Variable | Expression | Range | Units |
|----------|------------|-------|-------|
| Web Thickness | web_thickness | [2.0, 10.0] | mm |
| Flange Width | flange_width | [15.0, 40.0] | mm |
| Fillet Radius | fillet_radius | [2.0, 8.0] | mm |

### Objectives (1)
| Objective | Direction | Weight | Source |
|-----------|-----------|--------|--------|
| Total Mass | minimize | 1.0 | mass_extractor |

### Constraints (1)
| Constraint | Condition | Threshold | Type |
|------------|-----------|-----------|------|
| Max Stress | <= | 250 MPa | hard |

## Methodology

### Algorithm
- **Primary**: TPE (Tree-structured Parzen Estimator)
- **Max Trials**: 100
- **Surrogate**: Disabled

### Physics Extraction
- Mass: Extracted from NX expression `total_mass`
- Stress: Von Mises stress from SOL101 static analysis

### Convergence Criteria
- Max trials: 100
- Early stopping: 20 trials without improvement

## Expected Outcomes

Based on the optimization setup:
- Expected improvement: 15-30% mass reduction (typical for thickness optimization)
- Key trade-offs: Mass vs. stress margin
- Risk factors: None identified
```

## Integration Points

- **Backend**: `api/services/claude_readme.py` calls Claude API with this prompt
- **Endpoint**: `POST /api/intake/{study_name}/readme`
- **Trigger**: Automatic on status transition to `configured`