# godotiq_trace_flow — Usage Guide

## What It Does

`godotiq_trace_flow` traces how a game action flows through the entire Godot codebase. Given a trigger (exact function or signal name), it follows the chain of function calls and signal emissions across all `.gd` files and returns the complete execution path.

## MCP Tool Interface

```
godotiq_trace_flow(trigger, depth=10, detail="normal")
```

### Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `trigger` | string | required | Exact function or signal name to trace |
| `depth` | int | 10 | Max recursion depth |
| `detail` | string | "normal" | Output detail: "brief", "normal", or "full" |

### Detail Levels

- **brief**: Minimal output — no failure_points, steps contain only file/function/action
- **normal**: Full output with failure_points and complete step data (emits, calls)
- **full**: Same as normal

### Return Value

```json
{
  "flow": [
    {
      "file": "res://order_manager.gd",
      "function": "accept_order",
      "line": 5,
      "action": "Emits: order_accepted",
      "emits": ["order_accepted"],
      "calls": []
    },
    {
      "file": "res://pipeline_controller.gd",
      "function": "_on_order_accepted",
      "line": 8,
      "action": "Calls: PrinterManager.reserve_printer",
      "emits": [],
      "calls": ["PrinterManager.reserve_printer"]
    }
  ],
  "failure_points": [
    {
      "step": 0,
      "condition": "not has_available",
      "consequence": "flow stops"
    }
  ],
  "files_involved": 3,
  "total_steps": 3
}
```

## What It Traces

1. **Signal emissions** — `signal_name.emit()` calls within function bodies
2. **Signal listeners** — `.connect()` wiring across all scripts
3. **Autoload method calls** — `AutoloadName.method()` calls (direct pattern only)
4. **Failure points** — Guard patterns like `if not x: return`, `if x == null: return`

## What It Does NOT Trace

- TSCN editor-wired signal connections
- Direct method calls between scripts (non-autoload)
- Substring/fuzzy trigger matching
- `has_node`/`get_node` autoload patterns
- Lambda signal targets
- Property access on autoloads (only method calls)

## Files

| File | Purpose |
|------|---------|
| `src/godotiq/tools/flow/__init__.py` | All implementation + MCP tool registration |
| `src/godotiq/server.py` | Import line for auto-registration |
| `src/godotiq/prompts/godot_development.md` | Tool documentation in prompt |
| `tests/test_tools/test_trace_flow.py` | 49 tests |
| `tests/test_tools/conftest.py` | trace_flow_session fixture |
| `tests/fixtures/trace_flow/` | 8-file fixture project |
