# Section 3: Creation Workflow Prompt

## Overview

This section adds a "Creation Workflow" section and `build_scene` error recovery entries to the MCP prompt file. The prompt guides the AI agent through a 6-phase workflow for creating scenes using `godotiq_build_scene`, and documents how to recover from common errors.

**No automated tests are required for this section.**

## Dependencies

- **section-01-python-tool**: The `godotiq_build_scene` tool must be registered as an MCP tool. This section references it by name but does not depend on it being implemented first (prompt content can be written in parallel).

## File to Modify

**`src/godotiq/prompts/godot_development_prompt_v2.md`**

This is the active MCP prompt file served to the AI agent.

## Current File Structure

1. Header + "DO NOT" rules
2. "CRITICAL: How to Build 3D Scenes"
3. "Token Efficiency (CRITICAL)"
4. "Mandatory Workflows"
5. "Tool Reference"
6. "Spatial Validation"
7. "Node Paths"
8. "GDScript Conventions"
9. "Error Recovery"

## Changes Required

### Change 1: Add "Creation Workflow" Section

Insert after the "CRITICAL: How to Build 3D Scenes" section, before "Token Efficiency":

```markdown
### Creation Workflow — `build_scene`

For scenes with many nodes (grids, scattered objects, paths), use `godotiq_build_scene` instead of individual `node_ops` calls. One `build_scene` call replaces dozens of `node_ops` add_child operations.

#### Phase 1: Setup Scene Structure

Use `nodes` mode to create container nodes, camera, and lights:

godotiq_build_scene(nodes=[
    {type: "Node3D", name: "Terrain"},
    {type: "Node3D", name: "Decorations"},
    {type: "Node3D", name: "Enemies"},
    {type: "Camera3D", name: "MainCamera", position: [0, 10, 10], rotation: [-45, 0, 0]},
    {type: "DirectionalLight3D", name: "Sun", rotation: [-60, 30, 0]}
])
godotiq_save_scene()
→ ASK USER to verify structure in editor

#### Phase 2: Build Terrain

Use `grid` mode for tile-based ground. Use `overrides` for special tiles:

godotiq_build_scene(parent="Terrain", grid={
    scene: "res://tiles/grass.tscn",
    prefix: "Tile",
    rows: 8, cols: 8,
    spacing: 2.0,
    overrides: {
        "3,0": {scene: "res://tiles/road.tscn"},
        "3,1": {scene: "res://tiles/road.tscn"}
    }
})
godotiq_save_scene()
→ ASK USER to verify terrain

#### Phase 3: Add Decorations

Use `scatter` mode for handpicked placements:

godotiq_build_scene(parent="Decorations", scatter={items: [
    {scene: "res://props/tree.tscn", name: "Tree1", position: [5, 0, 3]},
    {scene: "res://props/rock.tscn", name: "Rock1", position: [8, 0, 1]}
]})
godotiq_save_scene()
→ ASK USER to verify decorations

#### Phase 4: Add Key Objects

Use `godotiq_placement` to find safe positions, then `scatter` to place.

#### Phase 5: Create Scripts

Use `godotiq_script_ops` for game logic ONLY — NOT for scene construction.

#### Phase 6: Verify

godotiq_spatial_audit(scene="res://scenes/main.tscn")
godotiq_signal_map(detail="brief")
godotiq_save_scene()
→ ASK USER to do final visual check

#### Key Principles

- **Everything static goes in .tscn** via build_scene
- **One build_scene call per logical group**
- **Save and verify after each phase**
- **Grid** for repetitive, **scatter** for handpicked, **line** for paths
- **Max 256 nodes per call** — split larger layouts
```

### Change 2: Add `build_scene` Tool Reference Entry

In the "Tool Reference" section under "EDIT", after `godotiq_node_ops`, add:

```markdown
**`godotiq_build_scene`** — Batch node creation with high-level patterns: grid (tile maps), line (paths/fences), scatter (handpicked placements), nodes (mixed types). One call = one undo action. Max 256 nodes per call. Use `parent` to target a container node.
```

### Change 3: Add Error Recovery Entries

Append to the "Error Recovery" section:

```markdown
- `NO_SCENE` (build_scene) → Open a scene in the Godot editor first
- `PARENT_NOT_FOUND` (build_scene) → Check parent node name/path; create the parent node first if needed
- `NO_NODES` (build_scene) → Ensure exactly one mode (grid/line/scatter/nodes) with valid data
- Partial success (build_scene) → Check `errors` array, fix failed items, retry only those
- Node count limit (build_scene) → Split into multiple `build_scene` calls grouped by parent
```

### Change 4: Update "Build in .tscn" Examples

Update examples in "CRITICAL: How to Build 3D Scenes":

```
❌  Write map_builder.gd that creates 64 tiles in _ready()
✅  Use build_scene(grid=...) to add 64 tile instances in Main.tscn

❌  Write spawn_decorations.gd that places trees randomly
✅  Use placement to find positions, then build_scene(scatter=...) to add tree instances
```

### Change 5: Update "3D Scene Work" Mandatory Workflow

Add `build_scene` to the 3D workflow list:

```
godotiq_build_scene(grid=..., parent="Terrain")  → batch creation (grids, scatter, lines)
```

Use `build_scene` for creating multiple nodes. Use `node_ops` for individual edits.

## Verification

1. Markdown is well-formed
2. All tool names match registered MCP names exactly
3. 6-phase workflow is complete and ordered
4. Error recovery entries use correct error codes
5. Run `pytest tests/ -v` — no existing tests should break

## Implementation Notes (Post-Build)

**Actual file modified:**
- `src/godotiq/prompts/godot_development_prompt_v2.md`

**All 5 changes applied as planned:**
1. Creation Workflow section with 6 phases added after "Build 3D Scenes"
2. Tool reference entry for `godotiq_build_scene` added under EDIT section
3. Error recovery entries added (5 entries)
4. Build examples updated to use `build_scene` instead of `node_ops`
5. Mandatory 3D workflow updated with `build_scene` entry

**No deviations from plan.**
