trace

---
name: trace-5695dcdc27a8
description: Spawn agent to trace code flow via query tools — answer only, no context cost
user-invocable: true
disable-model-invocation: false
context: fork
agent: Explore
argument-hint: "<question about code flow>"
---
Trace the following code flow through the Alt-Tabby codebase:
"$ARGUMENTS"

## Available Query Tools

Run via `powershell -File tools/<name>`. These are the primary research tools — always prefer them over reading files directly.

### CALL CHAIN (primary tool for tracing)
```
query_callchain.ps1 <funcName> [-Depth N] [-Reverse]
```
Forward: shows what `<funcName>` calls, to N levels deep (default 2).
Reverse: shows what calls `<funcName>`, to N levels up.
Example: `powershell -File tools/query_callchain.ps1 GUI_Repaint -Depth 3`

### FUNCTION BODY
```
query_function.ps1 <funcName>
```
Extracts full function body with line numbers. Use when you need to understand WHAT a function does, not just what it calls.
Example: `powershell -File tools/query_function.ps1 GUI_TransitionTo`

### GLOBAL OWNERSHIP
```
query_global_ownership.ps1 <globalName>
```
Shows who declares, writes (with mutation count), and reads a global.
Example: `powershell -File tools/query_global_ownership.ps1 gGUI_State`

### GLOBAL MUTATIONS (detailed)
```
query_mutations.ps1 <globalName> [-Brief]
```
Shows every function that mutates a global, with guards (Critical sections, if-conditions) and literal values assigned. More detailed than ownership.
Example: `powershell -File tools/query_mutations.ps1 gGUI_State`

### IMPACT / BLAST RADIUS
```
query_impact.ps1 <funcName> [-Deep]
```
Shows callers, globals written, downstream readers of those globals.
`-Deep` adds transitive callers (callers of callers).
Example: `powershell -File tools/query_impact.ps1 GUI_Repaint -Deep`

### FILE INTERFACE
```
query_interface.ps1 <filename>
```
Public functions + globals for a file (like `help(module)`). Accepts filename with or without `.ahk` extension.
Example: `powershell -File tools/query_interface.ps1 gui_paint`

### INCLUDE CHAIN
```
query_includes.ps1 [filename]
```
No args: full include tree from entry points.
With filename: who includes this file, what it includes, transitive entry points.
Example: `powershell -File tools/query_includes.ps1 gui_state.ahk`

### FUNCTION VISIBILITY
```
query_function_visibility.ps1 <funcName>
```
Where defined, public/private, all callers across all files.
Example: `powershell -File tools/query_function_visibility.ps1 _GUI_FreezeDisplayList`

### CONFIG
```
query_config.ps1 [keyword | -Section <name> | -Usage <propertyName>]
```
No args: section/group index. Keyword: fuzzy search. `-Usage`: which files read `cfg.X`.
Example: `powershell -File tools/query_config.ps1 -Usage ThemeMode`

### IPC MESSAGES
```
query_ipc.ps1 [message]
```
No args: list all `IPC_MSG_*` constants. With message: who sends/handles it.
Example: `powershell -File tools/query_ipc.ps1 snapshot`

### STATE MACHINE
```
query_state.ps1 [state] [event]
```
No args: index of all states/events. With args: specific dispatch branch.
Hardcoded to `GUI_OnInterceptorEvent` in `gui_state.ahk`.
Example: `powershell -File tools/query_state.ps1 ACTIVE TAB_STEP`

### TIMERS
```
query_timers.ps1 [keyword]
```
No args: full SetTimer inventory. With keyword: fuzzy filter.
Example: `powershell -File tools/query_timers.ps1 heartbeat`

### WINDOWS MESSAGES
```
query_messages.ps1 [query]
```
No args: list all `WM_` handlers. With query: hex, `WM_` name, or handler function.
Example: `powershell -File tools/query_messages.ps1 WM_CTLCOLORSTATIC`

## Research Instructions

1. **ALWAYS prefer query tools over reading files directly** — they return semantic answers and cost far less context
2. **Start with `query_callchain.ps1`** as the primary tracing tool
3. Use `query_function.ps1` ONLY when call chain output doesn't explain what a step does
4. Use `query_global_ownership.ps1` or `query_mutations.ps1` when the question involves data flow through globals
5. Use `query_impact.ps1` when the question is about what a change would affect
6. Use `query_interface.ps1` to understand a module's API surface before diving into specifics

## Response Format

Return ONLY a synthesized answer in this exact format:

## Summary
One sentence: what the flow does end-to-end.

## Path
1. FunctionName (file.ahk:line) — what this step does
2. FunctionName (file.ahk:line) — what this step does
...

## Key State
- globalName (owner: file) — role in this flow
- globalName (owner: file) — role in this flow

Maximum 30 lines total. No raw tool output. No reasoning about your research process.