# Sprint 10a: Agent Efficiency & Quality Assurance — Usage Guide

## What Was Built

Four improvements to make GodotIQ agents faster, more aware, and self-checking.

### 1. `_editor_state` in Every Bridge Response

Every bridge tool response now automatically includes:

```json
{
  "_editor_state": {
    "open_scene": "res://Main.tscn",
    "game_running": false,
    "recent_errors": ["Error at tower.gd:40 ..."]
  }
}
```

- **No more separate `editor_context` calls** — the agent knows the editor state after every tool call
- **Error visibility** — runtime errors from the debugger are captured in a ring buffer (max 10) and the 3 most recent are included
- **Survives output truncation** — `apply_output_limit()` preserves `_editor_state` even when truncating large responses

**Files:**
- `godot-addon/addons/godotiq/godotiq_server.gd` — `_get_editor_state()`, `_record_error()`, injected in `send_response()` and `_send_error()`
- `godot-addon/addons/godotiq/godotiq_debugger.gd` — wires `godotiq:error` messages to `_record_error()`
- `src/godotiq/tools/output_limit.py` — preserves `_editor_state` during truncation
- `tests/test_tools/test_editor_state.py` — 9 tests

### 2. Pre-flight Scene Checks

`node_ops` and `build_scene` now run `_preflight_scene_check()` before executing:
- **No scene open** → clear error with instructions: "Call godotiq_exec to open a scene first: `EditorInterface.open_scene_from_path('res://YourScene.tscn')`"
- **Wrong scene open** → clear error with switch instructions

**Files:**
- `godot-addon/addons/godotiq/godotiq_server.gd` — `_preflight_scene_check()` function, integrated in `_handle_node_ops` and `_handle_build_scene`

### 3. Grid Connectivity Validation

`build_scene` with grid mode + overrides now validates tile connectivity:
- Uses 4-connectivity (up/down/left/right) to detect isolated tiles
- Returns `"warnings"` list in the response
- Excludes tiles with custom `"position"` from validation
- Agent can immediately fix gaps without waiting for user to notice

**Files:**
- `src/godotiq/tools/bridge/build_scene.py` — `validate_grid_connectivity()` function + integration in `build_scene()`
- `tests/test_tools/test_build_scene.py` — 11 new tests

### 4. MCP Prompt: QA Checklist & Efficiency Rules

Two new sections in `godot_development_prompt_v2.md`:

- **MANDATORY: Final QA** — 6-step checklist (spatial audit, grid connectivity, code quality, signal wiring, gameplay test, user report) that the agent must complete before declaring "done"
- **Efficiency Rules** — 5 rules (don't overthink, batch operations, don't repeat calls, check `_editor_state`, one-script-one-validate)

**Files:**
- `src/godotiq/prompts/godot_development_prompt_v2.md` — two new sections
- `tests/test_prompts/test_prompt_content.py` — 12 tests

## Test Coverage

997 tests pass. New tests added: 9 (editor state) + 11 (grid validation) + 12 (prompt content) = 32 new tests.

## Commits

```
93f2582 Add _editor_state to every bridge response for ambient context
38a0042 Implement section 02: Pre-flight scene checks for node_ops and build_scene
2135620 Implement section 03: Grid connectivity validation for build_scene
74052eb Implement section 04: Add QA checklist and efficiency rules to MCP prompt
```
