# Enforcing Read-Modify-Write Pattern for Policy Updates

## Summary

The `update_workload_scaling_policy` tool has been redesigned to **force** LLMs to follow a read-modify-write pattern before updating policies.

## What Changed

### Before (Merge Pattern)
```python
update_workload_scaling_policy(
    cluster_id="...",
    policy_id="...",
    apply_type="IMMEDIATE",  # Individual fields
    confirm_update=True
)
```

**Problem**: LLMs could attempt updates without first reading the current policy, potentially missing important context or required fields.

### After (Full Object Pattern)
```python
# Step 1: Get current policy (REQUIRED)
current_policy = get_workload_scaling_policy(cluster_id, policy_id)

# Step 2: Modify the policy object
current_policy["applyType"] = "IMMEDIATE"
current_policy["recommendationPolicies"]["cpu"]["overhead"] = 0.15

# Step 3: Update with the complete modified policy
update_workload_scaling_policy(
    cluster_id=cluster_id,
    policy_id=policy_id,
    updated_policy=current_policy,  # Full object required
    confirm_update=True
)
```

**Solution**: The tool now REQUIRES the complete policy object, forcing LLMs to call `get_workload_scaling_policy` first.

## How It Enforces the Pattern

### 1. **Required Parameter Validation**
The tool validates that `updated_policy` contains required fields like `name` and `applyType`. If these are missing, it returns:

```json
{
  "error": "Missing required fields in updated_policy",
  "missing_fields": ["name", "applyType"],
  "hint": "Did you forget to call get_workload_scaling_policy() first?",
  "required_workflow": [
    "1. current = get_workload_scaling_policy(cluster_id, policy_id)",
    "2. Modify current policy: current['applyType'] = 'IMMEDIATE'",
    "3. update_workload_scaling_policy(cluster_id, policy_id, current, True)"
  ]
}
```

### 2. **Clear Documentation**
The tool description explicitly shows the required workflow:

```python
"""
⚠️  REQUIRED WORKFLOW - This tool enforces a read-modify-write pattern:

Step 1: Get current policy
    current_policy = get_workload_scaling_policy(cluster_id, policy_id)

Step 2: Modify the policy JSON
    current_policy["applyType"] = "IMMEDIATE"

Step 3: Update with the complete modified policy
    update_workload_scaling_policy(...)
"""
```

### 3. **Automatic Change Detection**
The tool:
- Still fetches the current policy internally (for comparison)
- Compares `updated_policy` vs `current_policy`
- Shows exactly what changed before applying updates
- Prevents no-op updates

### 4. **Two-Step Confirmation**
Before executing:
1. Shows detected changes and risk assessment
2. Requires `confirm_update=True` to proceed

## Benefits

✅ **Forces awareness**: LLMs must see current config before modifying
✅ **Prevents blind updates**: Can't update without knowing the structure
✅ **Better error messages**: Guides LLMs to the correct workflow
✅ **Change visibility**: Shows exactly what will be modified
✅ **Type safety**: Full object ensures all required fields are present

## Example Usage

### Correct Workflow
```python
# 1. Get current policy
response = get_workload_scaling_policy(
    cluster_id_or_name="production-cluster",
    policy_id="550e8400-e29b-41d4-a716-446655440000"
)
policy = json.loads(response)

# 2. Make targeted modifications
policy["applyType"] = "IMMEDIATE"
policy["recommendationPolicies"]["cpu"]["overhead"] = 0.15
policy["recommendationPolicies"]["memory"]["overhead"] = 0.10

# 3. Preview changes (confirm_update=False)
preview = update_workload_scaling_policy(
    cluster_id_or_name="production-cluster",
    policy_id="550e8400-e29b-41d4-a716-446655440000",
    updated_policy=policy,
    confirm_update=False  # Shows diff without applying
)

# 4. Apply changes
result = update_workload_scaling_policy(
    cluster_id_or_name="production-cluster",
    policy_id="550e8400-e29b-41d4-a716-446655440000",
    updated_policy=policy,
    confirm_update=True  # Actually applies the update
)
```

### What Happens If LLM Skips Step 1

If an LLM tries to create a policy object from scratch:

```python
# ❌ This will fail
update_workload_scaling_policy(
    cluster_id_or_name="production-cluster",
    policy_id="550e8400-e29b-41d4-a716-446655440000",
    updated_policy={"applyType": "IMMEDIATE"},  # Missing required fields!
    confirm_update=True
)
```

**Error response:**
```json
{
  "error": "Missing required fields in updated_policy",
  "missing_fields": ["name"],
  "hint": "Did you forget to call get_workload_scaling_policy() first?"
}
```

This error forces the LLM to follow the correct workflow.

## Migration Notes

If you had any documentation or examples using the old API, update them to use the new workflow pattern shown above.

## Testing

Test the enforcement by trying to update without calling `get_workload_scaling_policy` first - the tool should reject the request with helpful error messages guiding toward the correct workflow.