profile-coverage

name	profile-coverage
description	Review profiler instrumentation coverage and recommend new instrumentation points
user-invocable	true
disable-model-invocation	true

Enter planning mode. Review which functions are instrumented for profiling and identify gaps. This is a review/discussion step — do not implement instrumentation changes without approval.

Background

Alt-Tabby has a build-time strip profiler (src/shared/profiler.ahk). Functions are instrumented with Profiler.Enter("FuncName") ; @profile / Profiler.Leave() ; @profile pairs. In release builds, tools/compile.ps1 strips all ; @profile lines — true zero cost. In --profile builds, the profiler records QPC-timestamped events to a ring buffer and exports speedscope flame graphs.

The static analysis check validates balanced Enter/Leave per function (sub-check profile_markers in tests/check_batch_directives.ps1) — catches the early-return problem.

Step 1 — Generate the instrumentation map

Run:

powershell -File tools/query_instrumentation.ps1 -Save

This writes temp/INSTRUMENTATION_MAP.md with every function in src/gui/, src/core/, src/shared/ and whether it's currently instrumented.

Read it and summarize: how many functions total, how many instrumented, coverage %.

Step 2 — Classify uninstrumented functions

For every uninstrumented function, research it and classify:

• YES — Recommend instrumenting. In hot path or can block/delay it.
• MAYBE — Useful for specific investigations but not essential.
• NO — Trivial, one-shot, or never delays user interaction.

Use query_function.ps1 <name> to read function bodies. Use query_interface.ps1 <filename> to see a file's public API.

What counts as "hot path relevant"

The hot path is: Alt down → Tab → show overlay → paint → Alt up → activate window. But "hot path relevant" is BROADER than "directly in the hot path." It includes:

1. Directly in the path: interceptor callbacks, state machine, paint, activation
2. Can BLOCK the path: Any function that holds Critical "On" and runs on a timer or Windows callback. If it's executing when the user presses Alt, the Critical section blocks the hotkey callback until it finishes.
3. Can DELAY the path: Functions that produce data the hot path consumes. If they're slow, the hot path waits on stale/missing data or cache misses.

A function running on a 5-second background timer that holds Critical for 50ms IS hot-path-relevant because there's a 1% chance per Alt-Tab that it's mid-execution.

Parent/child discrimination

Before classifying any MAYBE, check: is its parent already instrumented? Are its children?

When the parent IS instrumented:

• Child is always <1ms → NO. Parent captures the aggregate.
• Child is variable and you can't tell which child is slow → YES. Need per-child spans.

When the children ARE instrumented:

• Parent is just a dispatcher with <10μs own work → NO. Children already show the time.
• Parent is called at high frequency (100+/sec) → NO, strongly. Buffer pollution.

When siblings ARE instrumented but there's a gap:

• Unexplained time between instrumented phases → YES. Subtraction-based inference is exactly what profilers eliminate.

When instrumenting a proposed-YES parent:

• Contains a variable-cost sub-call (COM, subprocess, DllCall that can block) → instrument BOTH. Parent gives total, child gives breakdown.

Known instrumentation gap: D3D11 / compositor pipeline

Post-#177, the rendering pipeline has extensive uninstrumented hot paths. The profiler currently covers GUI_Repaint (total paint time) but not the breakdown within:

• Shader pre-render (Shader_PreRender in d2d_shader.ahk): 40+ COM calls per shader per frame (cbuffer map, compute dispatch, D3D11 state setup, Draw, GPU→CPU readback). Runs N times per frame (once per active shader layer + mouse + selection + hover). Zero instrumentation currently.
• Effect compositing (FX_DrawShaderLayers, FX_DrawMouseEffect, FX_DrawSelectionEffect, FX_DrawHoverEffect in gui_effects.ahk): DrawImage calls for intermediate texture compositing. Only mouse effect has QPC measurement (for adaptive FPS skip).
• DComp operations (D2D_SetClipRect, D2D_Commit in gui_overlay.ahk): Clip update + commit on resize. No timing.
• Frame pacing (_Anim_FrameLoop in gui_animation.ahk): Compositor clock wait / waitable signal / spin-wait. Frame delta computed (gAnim_FrameDt) but not profiler-instrumented.

When classifying functions, pay special attention to these areas — they represent the majority of per-frame GPU-side cost but are invisible to the profiler.

What does NOT need instrumentation

• Property accessors, flag checks, arithmetic (<1μs)
• One-shot init/teardown (startup, shutdown, config reload)
• Per-element inner loops (instrument the parent loop instead — avoids buffer flooding)
• Recursive sort internals (instrument top-level call, not inner recursion)
• Dispatcher/wrapper functions whose children are already instrumented
• High-frequency callbacks (100+/sec) where own work is <10μs
• User-initiated deliberate actions (blacklist add, config save) — not latency-sensitive

Step 3 — Summary table

Produce a summary of all YES recommendations:

File	Function	Why (one line)
gui_paint.ahk	_GUI_PaintOverlay	Variable cost per-item, parent GUI_Repaint can't show which item is slow

And a count: "X new functions recommended, bringing total from Y to Z (N% coverage)."

Step 4 — Report and discuss

Present the summary table and ask if the user wants to discuss any items before implementation. Do NOT implement instrumentation changes in this skill — it is review only.