| name | investigate |
| description | Guide diagnosis of a user-reported symptom — map to diagnostics, collect data, analyze |
| user-invocable | true |
| disable-model-invocation | false |
| argument-hint | [symptom] |
The user is reporting a symptom or bug. Your job is to figure out what data is needed to diagnose it, guide the user to collect that data, then analyze the results.
Step 1 — Understand the symptom
Read the user's description and classify into one or more categories:
| Category | Symptoms | Primary Diagnostics |
|---|
| Keyboard/input | Lost keypresses, Alt-Tab not triggering, stuck overlay, wrong state | EventLog, AltTabTooltips, FlightRecorder |
| Focus/activation | Wrong window activated, activation fails, focus not set, window behind others | WinEventLog, EventLog, FlightRecorder |
| Window list | Missing windows, ghost windows, wrong order, stale titles | StoreLog, ChurnLog, FlightRecorder |
| Workspace | Wrong workspace detected, windows on wrong workspace, stale list after switch | KomorebiLog, WinEventLog, FlightRecorder |
| Overlay/visual | Flicker, wrong position, wrong size, rendering glitches, slow paint | PaintTimingLog, AltTabTooltips, FlightRecorder |
| Icons/process | Missing icons, wrong icons, missing process names | IconPumpLog, ProcPumpLog, IPCLog |
| Startup/lifecycle | Won't start, subprocess not launching, crash on startup | LauncherLog, StoreLog |
| Config editor | WebView2 issues, settings not saving, editor crash | WebViewLog |
| Bypass mode | Alt-Tab works in some apps but not others, game mode issues | WinEventLog, EventLog, FlightRecorder |
Multiple categories often overlap — a "wrong window activates" bug may need both focus and workspace diagnostics.
Step 2 — Tell the user what to enable
Based on the classification, tell the user exactly what to do. Be specific — config key names, not vague instructions.
Always recommend
- FlightRecorder — should already be enabled by default (
[Diagnostics] FlightRecorder=true). Confirm with the user. If not enabled, this is the first thing to turn on.
Category-specific diagnostics
Tell the user which keys to set in config.ini under [Diagnostics]:
; Example for a focus/activation issue:
[Diagnostics]
WinEventLog=true
EventLog=true
All logs write to %TEMP%\ with tabby_ prefix. Tell the user the exact log filenames they'll need to provide (from the table in .claude/rules/debugging.md).
Reproduction instructions
Tell the user:
- Enable the diagnostics listed above in
config.ini
- Restart Alt-Tabby (diagnostics are read at startup)
- Reproduce the issue
- Immediately press F12 (or their configured FlightRecorder hotkey) to capture a dump
- Provide: the flight recorder dump from
release/recorder/ AND the relevant log files from %TEMP%\
If the issue is intermittent, tell the user to leave diagnostics enabled and capture a dump each time it occurs. Multiple dumps help with correlation.
Step 3 — Analyze the data
When the user provides data:
Flight recorder dumps
Use the analysis method from /flight-recorder — trace event chains, check global state, find broken sequences, timing gaps.
Log files
Read the log files and correlate timestamps with the flight recorder dump. Look for:
- Events in the log that correspond to the symptom timeframe
- Error messages or unexpected states
- Patterns across multiple occurrences
Cross-correlation
The power is in combining sources:
- FlightRecorder shows what happened (event sequence)
- WinEventLog shows what Windows reported (focus changes, window events)
- EventLog shows what the keyboard hook saw (key events, state transitions)
- KomorebiLog shows what komorebi reported (workspace changes, window moves)
- PaintTimingLog shows how long rendering took
Match timestamps across sources to build the full picture.
Step 4 — Diagnose or escalate
If the cause is clear:
- Explain the root cause with evidence from the data
- Point to the relevant code (use query tools —
query_state.ps1 for state machine issues, query_messages.ps1 for message handlers, query_events.ps1 <code> to look up event field meanings and emitter functions)
- Suggest whether this is a bug to fix or a known limitation
If the cause is unclear:
- Explain what you've ruled out
- Suggest additional diagnostics that might help
- Ask the user to reproduce with more verbose logging if available
When the user provides no data yet
If the user just describes a symptom with no dumps or logs, go directly to Step 2 — tell them what to enable and how to reproduce. Don't speculate without data.
