# Section 4: MCP Prompt Update

## Overview

This section updates the MCP prompt file `src/godotiq/prompts/godot_development.md` with a new "Spatial Validation" subsection. This is a documentation-only change -- no code or tests are needed.

**File to modify:** `/Users/salvatorefarruggio/Desktop/godotiq/src/godotiq/prompts/godot_development.md`

**Dependencies:** None. This section can be implemented in parallel with all other sections.

## Tests

No tests are needed for this section. It is purely a documentation change to an MCP prompt file.

From the TDD plan:

> Section 4: MCP Prompt Update -- No tests needed -- this is a documentation-only change.

## Background

GodotIQ serves an MCP prompt (`godot_development.md`) that AI agents receive as guidance for how to use the tools. Sprint 5f adds spatial validation to `godotiq_node_ops`, allowing agents to include `validate: true` on move, scale, or add_child operations. The prompt must be updated so agents know this capability exists and how to use it properly.

The spatial validation system works as follows:

- When an operation in a `godotiq_node_ops` call includes `validate: true`, the tool reads the `.tscn` scene file from disk and checks the target position/scale against the scene's spatial context before executing.
- If a position is invalid (inside a wall, overlapping another node), execution is **blocked** with a diagnostic message.
- Three severity levels exist: **OK** (all clear), **WARNING** (suspicious but allowed), **BLOCKED** (operation refused, no changes made).
- Batch behavior is **atomic**: if any single operation in a batch is BLOCKED, none of the operations execute.
- An optional `scene` parameter on `godotiq_node_ops` specifies which `.tscn` file to validate against. If omitted, the main scene from `project.godot` is used.
- Validation reads from disk, so unsaved editor changes are not reflected. Agents should call `godotiq_save_scene` before validated operations if they have made prior unsaved changes.

## Implementation Details

### What to Add

Add a **"Spatial Validation"** subsection to the prompt file. The best placement is within the existing `### Moving/Placing Objects in 3D` workflow section, or immediately after the `godotiq_node_ops` tool description in the EDIT category. Specifically, insert the new subsection **after the Workflows section and before the GDScript Conventions section**, or integrate it into the existing Moving/Placing Objects workflow.

The recommended approach is two changes:

1. **Add a "Spatial Validation" subsection** after the Workflows section (before "GDScript Conventions"). This is the main documentation block.
2. **Update the Moving/Placing Objects workflow** to include `validate: true` in the node_ops step.

### Content for the Spatial Validation Subsection

The new subsection should cover all of the following points:

**How to use `validate: true`:**
- Add `"validate": true` to any `move`, `scale`, or `add_child` operation dict within a `godotiq_node_ops` call.
- When present, the tool checks the target position/scale against the scene's spatial layout before executing.

**The `scene` parameter:**
- `godotiq_node_ops` accepts an optional `scene` parameter (string) specifying which `.tscn` file to validate against.
- If omitted, defaults to the project's main scene from `project.godot`.
- Accepts `res://` paths or absolute filesystem paths.

**Severity levels:**
- **OK** -- Position/scale is valid. Operation proceeds.
- **WARNING** -- Position/scale is suspicious (e.g., far from siblings, near a wall but not inside it). Operation proceeds but the warning is returned in the response.
- **BLOCKED** -- Position is invalid (inside a wall, overlapping another node). Operation is refused. No changes are made.

**Atomic batch behavior:**
- If ANY operation in a batch is BLOCKED, NONE of the operations execute -- even operations without `validate: true`.
- This prevents partial modifications that would leave the scene in an inconsistent state.

**Recommendations:**
- Always use `validate: true` when moving or placing objects in 3D scenes.
- Call `godotiq_save_scene()` before validated operations if you have made prior unsaved changes via `node_ops`, because validation reads `.tscn` files from disk and unsaved editor changes are not reflected.
- If an operation is BLOCKED, read the diagnostic message -- it tells you what spatial constraint was violated (wall proximity, overlap, etc.) and which node caused the conflict.

**Example usage:**

The subsection should include an example like:

```
godotiq_node_ops(
  operations=[
    {"op": "move", "node": "StorageShelf_04", "position": [2.5, 0.0, -1.0], "validate": true},
    {"op": "add_child", "parent": "Entities", "scene": "res://scenes/worker.tscn",
     "position": [3.0, 0.0, 0.0], "validate": true}
  ],
  scene="res://scenes/main.tscn"
)
```

### Update to the Moving/Placing Objects Workflow

The existing workflow in the prompt file currently reads:

```
### Moving/Placing Objects in 3D
1. godotiq_scene_map(scene, focus=target_area)    -> understand space
2. godotiq_scene_tree(root=parent_node)            -> see live state
3. godotiq_node_ops(operations=[move/add_child])   -> execute change
4. godotiq_scene_tree(root=changed_area)           -> verify result
5. godotiq_save_scene()                            -> persist to disk
```

Update step 3 to mention `validate: true`:

```
3. godotiq_node_ops(operations=[{..., validate: true}])  -> execute with validation
```

### Update to the Error Recovery Section

The existing Error Recovery section at the bottom of the file should gain one new entry for the BLOCKED status from spatial validation:

```
- `BLOCKED` (from node_ops validation) -- Spatial validation rejected the operation. Check the diagnostic message for which constraint failed (wall proximity, overlap). Adjust position and retry.
```

This is distinct from the existing `BLOCKED` entry for exec (which is about blocked code patterns). The parenthetical qualifier distinguishes them.

### Placement Summary

In total, the changes to `src/godotiq/prompts/godot_development.md` are:

1. Update the `godotiq_node_ops` bullet in the EDIT tools list to mention `validate: true` and the `scene` parameter briefly (one line addition).
2. Update step 3 of the "Moving/Placing Objects in 3D" workflow.
3. Add a new `## Spatial Validation` subsection after the Workflows section, before GDScript Conventions. This is the main documentation block containing usage details, severity levels, atomic behavior, recommendations, and example.
4. Add a BLOCKED entry to the Error Recovery section for node_ops validation.

## Actual Implementation

All four planned changes were implemented as specified:

1. **node_ops bullet** (lines 56-57): Added two lines for `validate: true` and `scene` parameter.
2. **Workflow step 3** (line 126): Updated to `godotiq_node_ops(operations=[{..., validate: true}])`.
3. **Spatial Validation subsection** (lines 168-202): Added full `## Spatial Validation` section with parameters, severity levels, checks (wall proximity, overlap, sibling outlier, scale outlier), atomic batch behavior, example code, and recommendations.
4. **Error Recovery** (line 270): Added `BLOCKED (from node_ops)` entry distinct from the exec BLOCKED entry.

No deviations from the plan.