# Sprint Token Optimization — Tutti i Tool

## Problema

I tool GodotIQ restituiscono output troppo grandi per il context window
di Claude Code (~200k token). Esempio reale: `asset_registry` su un progetto
con 670 modelli genera 140k caratteri (4932 righe) da una singola chiamata.
`scene_map(detail="full")` su una scena con 876 nodi genera output simile.

Questo rende GodotIQ inutilizzabile su progetti reali. L'agent esaurisce
il context window in 4 minuti.

## Obiettivo

Dopo questo sprint:
- Nessun tool restituisce più di **2000 caratteri** con `detail="brief"`
- Nessun tool restituisce più di **8000 caratteri** con `detail="normal"`
- `detail="full"` è l'unico che può restituire output illimitato
- **Default è "normal"** per tutti i tool
- Tool che accettano filtri hanno parametri aggiuntivi per restringere l'output

## Modifiche richieste

### A. Parametro `detail` su TUTTI i tool che restituiscono dati variabili

Aggiungi il parametro `detail: str = "normal"` (valori: "brief", "normal", "full")
a tutti i tool elencati sotto. Il parametro deve essere documentato nella docstring.

---

### Tool-by-tool specification

#### 1. `asset_registry`
File: `src/godotiq/tools/assets/` (o dove si trova)

Nuovi parametri:
- `detail: str = "normal"`
- `path_filter: str = ""` — filtra per sottocartella (es. "kenney_furniturekit")
- `max_results: int = 50` — limite risultati per categoria

Output per detail level:
```
brief (~20-30 righe):
  Summary: 395 assets (153 models, 220 textures, 14 audio, 8 resources)
  Models: 659 files, 29 used in scenes, 630 unused
  Issues: 0 missing references, 0 unused
  Top unused models: [primi 5 con path]

normal (~80-100 righe):
  [tutto brief] +
  Models by directory:
    kenney_furniturekit/: 170 files (16 used)
    kenney_spacekit/: 45 files (12 used)
    decorations/: 23 files (1 used)
    ...
  Used assets list: [tutti gli asset usati con scene che li referenziano]
  Issues detail: [lista completa problemi]
  Top 20 unused: [path + dimensione]

full (illimitato):
  [comportamento attuale — lista completa di ogni file]
```

#### 2. `scene_map`
File: `src/godotiq/tools/spatial/`

Nuovi parametri (se non già presenti):
- `detail: str = "normal"`
- `max_nodes: int = 50` — limite nodi nell'output

Output per detail level:
```
brief (~20-30 righe):
  Scene: main.tscn (876 nodes total)
  World bounds: (-10, 0, -15) → (10, 5, 5)
  Zones/rooms: [lista nomi con bounds]
  Node type summary: 45 MeshInstance3D, 23 StaticBody3D, 12 Marker3D, ...
  Anomalies: [solo critiche]

normal (~100-150 righe):
  [tutto brief] +
  Focus area nodes: [nodi filtrati per focus+radius, max 50]
  Ogni nodo: name, type, position, script (se ha), groups
  Nearby summary per focus_node
  Markers list
  All anomalies

full (illimitato):
  [comportamento attuale — ogni singolo nodo]
```

#### 3. `spatial_audit`
File: `src/godotiq/tools/spatial/`

Parametri:
- `detail: str = "normal"`
- `max_issues: int = 20`

```
brief: conteggi per check + solo issue critical/high
normal: brief + tutte le issue fino a max_issues per categoria
full: tutto
```

#### 4. `dependency_graph`
File: `src/godotiq/tools/code/`

Parametri:
- `detail: str = "normal"`

```
brief (~15-20 righe):
  File: path.gd
  Class: ClassName | Autoload: yes/no
  Depends on: [lista nomi, no dettagli]
  Depended by: [lista nomi, no dettagli]
  Impact: HIGH/MEDIUM/LOW

normal (~40-60 righe):
  [tutto brief] +
  Emits signals: [signal → listeners list]
  Listens to: [signal → handler]
  References detail at depth=2

full: tutto con depth illimitato
```

#### 5. `signal_map`
File: `src/godotiq/tools/code/`

Parametri:
- `detail: str = "normal"`
- `max_results: int = 30`

```
brief (~15-20 righe):
  Total: 47 signals, 83 connections
  Orphans: 4 (list names only)
  Busiest: top 5 signal → N listeners
  Missing: N

normal: brief + full orphan detail + full busiest + all missing
full: every signal with every connection
```

#### 6. `trace_flow`
File: `src/godotiq/tools/flow/`

Parametri:
- `detail: str = "normal"`

```
brief (~10-15 righe):
  Flow: trigger → [file1 → file2 → file3 → ... → end]
  Files involved: N
  Failure points: N

normal: brief + ogni step con file, action, emits + failure point details
full: normal + codice sorgente rilevante per ogni step
```

#### 7. `project_summary`
File: `src/godotiq/tools/memory/`

Parametri:
- `detail: str = "normal"`

```
brief (~10-15 righe):
  Project: name | Engine: Godot 4.x | Type: 3D
  Stats: N scripts, N scenes, N assets
  Autoloads: [lista nomi]
  Main scene: path

normal (~30-50 righe):
  brief + architecture overview + recent changes + known issues

full: normal + complete autoload detail + all scenes list
```

#### 8. `file_context`
File: `src/godotiq/tools/memory/`

Parametri:
- `detail: str = "normal"`

```
brief (~10-15 righe):
  File: path | Lines: N | Class: name | Autoload: yes/no
  Role: one-line description
  Depends on: [lista]
  Depended by: [lista]

normal: brief + public API + gotchas
full: normal + full source analysis
```

#### 9. `validate`
File: `src/godotiq/tools/code/`

Parametri:
- `detail: str = "normal"`
- `max_issues: int = 30`

```
brief: N errors, N warnings. Top 5 issues.
normal: all issues up to max_issues
full: all issues + auto-fix suggestions + context
```

#### 10. `animation_info`
File: `src/godotiq/tools/animation/`

Parametri:
- `detail: str = "normal"`

```
brief: N animations found. Names + duration + loop status.
normal: brief + track count + state machine + issues
full: normal + every track detail
```

#### 11. `animation_audit`
File: `src/godotiq/tools/animation/`

Parametri:
- `detail: str = "normal"`
- `max_issues: int = 20`

```
brief: N scenes scanned, N issues. Summary by severity.
normal: brief + all issues up to max_issues
full: everything
```

#### 12. `impact_check`
File: `src/godotiq/tools/code/`

Questo tool è già tipicamente compatto. Aggiungi `detail` per consistenza:
```
brief: risk level + number of callers + safe alternative (one line)
normal: current behavior
full: normal + test checklist + full caller context
```

#### 13. `placement`
File: `src/godotiq/tools/spatial/`

Questo tool è già tipicamente compatto. Aggiungi `detail`:
```
brief: top 1 suggestion with position + confidence
normal: top 3 suggestions + excluded zones + reasoning
full: all candidates evaluated + scoring detail
```

#### 14. `suggest_scale`
Già compatto. Aggiungi `detail` per consistenza.

#### 15. `diagnose`
File: `src/godotiq/tools/flow/`

```
brief: top cause + likelihood + files involved
normal: all causes with traces
full: normal + code excerpts
```

#### 16. Tool bridge (se hanno output variabile)
Controlla questi e aggiungi `detail` se il loro output può essere grande:
- `scene_tree` — SÌ, può essere grande. Stessa logica di scene_map.
- `state_inspect` — probabilmente OK così
- `perf_snapshot` — probabilmente OK così
- `ui_map` — SÌ, può essere grande su UI complesse. Aggiungi detail.
- `watch` — probabilmente OK
- `nav_query` — probabilmente OK

Per `scene_tree` e `ui_map`:
```
brief: conteggio + struttura a 1 livello di profondità
normal: struttura a 3 livelli
full: tutto
```

---

### B. Truncation safety net

Indipendentemente dal detail level, aggiungi una funzione helper che tutti
i tool usano prima di restituire l'output:

```python
def truncate_output(text: str, detail: str, tool_name: str) -> str:
    """Ensure output doesn't exceed limits for the given detail level."""
    limits = {
        "brief": 2000,
        "normal": 8000,
        "full": 200000,  # 200k chars max anche per full
    }
    max_chars = limits.get(detail, 8000)
    if len(text) <= max_chars:
        return text
    truncated = text[:max_chars - 200]
    remaining = text[max_chars - 200:]
    # Count what was cut
    lines_cut = remaining.count('\n')
    return (
        truncated
        + f"\n\n... truncated ({lines_cut} more lines). "
        + f"Use detail='full' for complete output."
    )
```

Metti questa utility in un file condiviso (es. `src/godotiq/utils.py` o
`src/godotiq/output.py`) e importala in ogni tool.

---

### C. Test

Per ogni tool modificato, aggiungi almeno 2 test:

1. **Test brief output size**: chiama il tool con `detail="brief"` su un
   progetto/fixture reale (o sufficientemente grande) e verifica che
   `len(output) < 3000` caratteri.

2. **Test normal output size**: chiama con `detail="normal"` e verifica
   `len(output) < 10000` caratteri.

3. **Test full backward compatibility**: chiama con `detail="full"` e
   verifica che l'output è uguale al comportamento precedente.

4. **Test path_filter** (solo asset_registry): verifica che filtrando
   per una sottocartella il risultato contiene solo asset di quella cartella.

5. **Test default è normal**: chiama senza specificare detail e verifica
   che l'output rispetta il limite normal.

### D. Test di integrazione token budget

Aggiungi un test che simula un workflow reale:

```python
def test_full_workflow_token_budget():
    """A realistic workflow should use less than 30k chars total."""
    total = 0

    result = project_summary(detail="brief")
    total += len(result)

    result = scene_map(detail="normal", focus="SomeNode", radius=5)
    total += len(result)

    result = asset_registry(detail="brief")
    total += len(result)

    result = spatial_audit(detail="brief")
    total += len(result)

    result = signal_map(detail="brief")
    total += len(result)

    assert total < 30000, f"Workflow used {total} chars, max 30000"
```

---

## Verifica finale

```bash
pytest tests/ -v
```

- Tutti i test esistenti passano (nessuna regressione)
- Nuovi test per detail levels passano
- Test token budget passa

## File da NON toccare
- File .gd nell'addon Godot
- File di configurazione (.mcp.json, .godotiq.json)
- Test esistenti (solo aggiungere, non modificare)

## Priorità

Se il tempo è limitato, fai ALMENO questi 4 tool (i più pesanti):
1. `asset_registry` (140k chars attuale → 2k brief)
2. `scene_map` (enorme su scene grandi → 2k brief)
3. `scene_tree` (se ha lo stesso problema)
4. `ui_map` (se ha lo stesso problema)

Gli altri tool sono meno urgenti perché generano output più piccoli,
ma vanno comunque fatti tutti per consistenza.
