# Sprint — Agent Efficiency & Quality Assurance

## Contesto

GodotIQ è un MCP server con 33 tool per sviluppo Godot 4 assistito da AI.
Il tool funziona — un agent ha costruito un Tower Defense 3D completo con
asset Kenney, 4 tipi di torri, 4 tipi di nemici, 8 wave, UI, effetti visivi,
tutto da un singolo prompt. Il gioco funziona al primo F5.

MA ci sono problemi di efficienza e qualità:

1. L'agent ci mette 25-30 minuti quando potrebbe farne 10-15
2. L'agent si blocca su cose ovvie (scena non aperta, errori non visti)
3. L'agent dichiara "fatto" senza controllare il risultato (path tile disconnessi)
4. L'agent non vede gli errori della console Godot

## FASE 1: Deep Research (fai PRIMA di implementare)

Analizza l'intero codebase di GodotIQ per capire dove l'agent perde tempo.
Leggi questi file in ordine:

1. `src/godotiq/prompts/godot_development.md` — il prompt MCP che guida l'agent
2. `src/godotiq/server.py` — come sono registrati i tool
3. `src/godotiq/tools/bridge/` — TUTTI i file. Capire cosa restituisce ogni tool
4. `godot-addon/addons/godotiq/godotiq_server.gd` — handler GDScript
5. `godot-addon/addons/godotiq/godotiq_debugger.gd` — cattura errori (se esiste)
6. `src/godotiq/tools/bridge/build_scene.py` — il tool nuovo
7. `src/godotiq/tools/bridge/node_ops.py` — come funziona editing
8. `src/godotiq/tools/bridge/scene_tree.py` — come vede il tree
9. `src/godotiq/tools/spatial/` — scene_map, spatial_audit, placement

Dopo aver letto tutto, rispondi a queste domande:

### Domande di ricerca

A) **Feedback loop**: Quando l'agent chiama `build_scene` o `node_ops`, cosa
   riceve indietro? Riceve abbastanza contesto per sapere se ha funzionato?
   O riceve solo "ok" e non sa cosa è successo realmente nell'editor?

B) **Errori Godot**: Quando Godot stampa un errore rosso nella console
   (tipo "Script error" o "Node not found"), l'agent lo vede? C'è un
   meccanismo per catturare e restituire errori dell'editor nei tool response?

C) **Editor awareness**: L'agent sa quale scena è aperta? Sa se il gioco
   è in esecuzione? O deve chiamare `editor_context` ogni volta? Perché
   non includiamo queste info automaticamente nelle response?

D) **Bottleneck di tempo**: Guardando il codice, dove credi che l'agent
   perda più tempo? Tool che rispondono lentamente? Tool che non danno
   abbastanza info e forzano chiamate extra? Tool che richiedono troppi
   parametri?

E) **Build workflow**: Il prompt MCP ha una sezione "Creation Workflow".
   È abbastanza chiara per guidare l'agent senza esitazioni? O ci sono
   ambiguità che lo fanno fermare a "pensare"?

F) **Quality control**: C'è qualcosa nel codice che potrebbe fare auto-QA?
   Per esempio, `build_scene` potrebbe verificare automaticamente la
   connettività dei tile nella griglia dopo averli piazzati?

Scrivi le risposte alle domande A-F prima di procedere alla Fase 2.

---

## FASE 2: Fix Obbligatori (implementa dopo la ricerca)

### Fix 1: Editor State in Every Bridge Response

Ogni tool bridge (node_ops, build_scene, save_scene, scene_tree, run,
screenshot, input, exec, state_inspect, camera) deve includere nel
response un campo `_editor_state` con informazioni minime:

```python
{
    # ... normal tool response ...
    "_editor_state": {
        "open_scene": "res://Main.tscn",      # o null se nessuna scena aperta
        "game_running": false,                  # true se il gioco è in esecuzione
        "recent_errors": ["Error at tower.gd:40 ..."],  # ultimi 3 errori, o [] se nessuno
    }
}
```

Questo elimina la necessità di chiamare `editor_context` separatamente.
L'agent riceve contesto a OGNI tool call. Se `open_scene` è null,
l'agent sa che deve aprire una scena prima di procedere.

**Implementazione**: nel handler GDScript, aggiungi una funzione helper
che raccoglie lo stato editor e lo attacca a ogni response:

```gdscript
func _get_editor_state() -> Dictionary:
    var state := {}
    var root := EditorInterface.get_edited_scene_root()
    state["open_scene"] = root.scene_file_path if root else ""
    state["game_running"] = EditorInterface.is_playing_scene()
    # Errori recenti dal debugger (se disponibili)
    state["recent_errors"] = _get_recent_errors()  # implementa basandoti su debugger.gd
    return state
```

E in ogni handler, prima di `send_response`:
```gdscript
var response := {
    # ... dati normali del tool ...
}
response["_editor_state"] = _get_editor_state()
send_response(peer_id, id, response)
```

### Fix 2: Pre-flight Checks in build_scene e node_ops

Prima di eseguire operazioni, build_scene e node_ops devono verificare:

1. Una scena è aperta → se no, errore chiaro: "No scene is open in the
   editor. Call godotiq_exec to open a scene first:
   EditorInterface.open_scene_from_path('res://Main.tscn')"

2. La scena è quella giusta (se specificata dal parametro `scene`) → se no,
   apri automaticamente la scena corretta prima di procedere

Questo è probabilmente già implementato parzialmente — verifica nel codice
e assicurati che il messaggio di errore sia actionable (dice all'agent
COSA FARE, non solo che qualcosa è sbagliato).

### Fix 3: Build Scene Auto-Validation

Dopo che `build_scene` ha creato i nodi, e PRIMA di restituire la response:

Se il mode è `grid` con `overrides` (cioè un path/strada):
1. Verifica che ogni tile override sia adiacente ad almeno un altro tile
   override (nessun tile isolato nel path)
2. Verifica che la distanza tra tile adiacenti del path sia esattamente
   `spacing` (±0.01 tolleranza)
3. Se trova disconnessioni, includi un warning nella response:
   ```json
   {
     "created": 64,
     "warnings": ["Path tile Path_2_3 at (2,0,3) has no adjacent path tile to the south — possible gap in road"]
   }
   ```

Questo fa sì che l'agent sappia subito che c'è un problema nel path
senza aspettare che l'utente lo noti visivamente.

**Implementazione**: nel handler GDScript `_handle_build_scene`, dopo
aver creato tutti i nodi e prima di `send_response`, se c'era un grid
con overrides, chiama `_validate_grid_connectivity(overrides, spacing)`.

### Fix 4: Prompt MCP — Final QA Checklist

Aggiungi questa sezione al file `src/godotiq/prompts/godot_development.md`.
Posizionala DOPO la sezione "Creation Workflow" e PRIMA di "Error Recovery":

```markdown
## MANDATORY: Final QA Before Declaring "Done"

After completing ANY build or modification task, you MUST run this checklist
BEFORE telling the user you're done. Do NOT skip any step.

### 1. Spatial Coherence
Call spatial_audit(detail="brief"). Must have 0 critical/warning issues.

### 2. Grid/Path Connectivity (if you built a grid or path)
Check the build_scene response for any warnings about disconnected tiles.
If warnings exist, fix the affected tiles with node_ops before continuing.
If no warnings but you built a road/path: call scene_map with focus on
the path area and verify every path tile connects to its neighbors.

### 3. Code Quality
Call validate(detail="brief") on every .gd file you created. Fix any errors.

### 4. Signal Wiring
Call signal_map(detail="brief", find="orphans"). Must be 0 orphans.
If orphans found, either connect them or remove the unused signal definitions.

### 5. Gameplay Test
If the game should be runnable:
- run(action="play"), wait 3 seconds
- state_inspect to verify initial values are correct
- Trigger one game action (start wave, click button) with input tool
- state_inspect to verify values changed as expected
- run(action="stop")

### 6. Report to User
Tell the user what was built and the QA results.
Then say: "Please open the project in Godot and visually confirm
everything looks correct. I cannot see the visual result."

NEVER say "I can see the terrain" or "the game looks great".
You CANNOT see. Always ask the user to verify visually.
```

### Fix 5: Prompt MCP — Efficiency Rules

Aggiungi questa sezione al prompt MCP, nella parte alta (dopo le regole
sui detail levels):

```markdown
## Efficiency Rules

### Don't overthink — act

When you know what to do, DO IT. Don't spend 2 minutes planning what
you'll do next. Call the tool. If it fails, you'll know immediately from
the response.

### Batch operations

Use build_scene for multiple nodes instead of individual node_ops calls.
Use script_ops patch mode for targeted changes instead of rewriting entire files.

### Don't repeat tool calls

If you already called project_summary this session, don't call it again.
If you already know the asset list, don't call asset_registry again.
Keep the information from previous calls in your working memory.

### Check editor_state in every response

Every bridge tool response includes _editor_state with open_scene,
game_running, and recent_errors. READ IT. If recent_errors is not empty,
address the errors before continuing. If open_scene is wrong or null,
fix it before doing more work.

### One script, one validate

After writing each .gd file, immediately call validate on it. Don't write
5 scripts and then validate them all — errors compound and become harder
to debug.
```

---

## FASE 3: Verifica

```bash
pytest tests/ -v  # tutti i test passano, nessuna regressione
```

Test manuale (se possibile):
1. Apri un progetto Godot con addon attivo
2. Chiama `build_scene(nodes=[{"type": "Node3D", "name": "TestNode"}])`
3. Verifica che la response contiene `_editor_state`
4. Chiudi la scena nell'editor (nessuna scena aperta)
5. Chiama `build_scene(nodes=[{"type": "Node3D", "name": "Test2"}])`
6. Verifica che la response è un errore con istruzione su come aprire la scena

## File da modificare

| File | Cosa |
|------|------|
| `godot-addon/addons/godotiq/godotiq_server.gd` | _get_editor_state() helper + attaccalo a TUTTE le response + _validate_grid_connectivity + pre-flight scene check migliorato |
| `src/godotiq/tools/bridge/build_scene.py` | Includi warnings di connettività nella response |
| `src/godotiq/prompts/godot_development.md` | QA checklist + efficiency rules |

## File da NON modificare
- Parser (tscn_parser, gd_parser, scene_resolver, project_index)
- Tool di analisi (scene_map, dependency_graph, signal_map, etc.)
- Tool bridge esistenti TRANNE per aggiungere _editor_state alla response
- Test esistenti (solo aggiungere nuovi)
