{
  "version": "act 2.0.0",
  "slug": "hot-path-refactor",
  "name": "hot-path-refactor",
  "description": "Use when deciding what to optimize or refactor for performance \u2014 ranks code by combining runtime profile hotness with static complexity and coupling, so effort lands where it is both expensive at runtime and hard to change.",
  "url": "https://act101.ai/docs/skills/hot-path-refactor",
  "body_md": "# Hot Path Refactor\n\nPrioritize performance/refactor effort on code that is both hot at runtime and structurally hard. Optimizing cold code wastes effort; optimizing hot-but-trivial code rarely pays; the wins are where hotness meets complexity.\n\n## When to use\n\n- Performance work where you need to choose targets with evidence.\n- Deciding which hot functions are worth refactoring vs. leaving alone.\n\n## Inputs\n\nA speedscope profile (py-spy/Austin or pprof\u2192speedscope) and the source tree. Overlays are MCP tools (Architecture tier).\n\n## Protocol\n\n1. **Hotness** \u2014 call `profile_overlay` with the speedscope report to rank symbols by `self_pct` (direct cost) and `total_pct` (inclusive cost).\n2. **Complexity** \u2014 call `analyze_hotspots` to rank files/functions by composite complexity (cyclomatic, statements, nesting).\n3. **Coupling** \u2014 call `analyze_coupling` to find how entangled a hot symbol's module is (refactoring a high-coupling hot path is riskier and higher-value).\n4. **Synthesize** \u2014 rank by hot \u00d7 hard: a symbol with high `self_pct` AND high complexity is the top refactor target (expensive and changeable). High `self_pct` + low complexity \u2192 consider an algorithmic/throughput fix, not a refactor. High `total_pct` but low `self_pct` \u2192 the cost is in callees; follow the stack.\n5. **Recommend** \u2014 for each top target, state the profile evidence (self/total %), the complexity signal, and a concrete next step (optimize in place / extract / reduce coupling first).\n\n## Output\n\nA ranked target list. Each: symbol id, `self_pct`/`total_pct`, complexity/coupling signals, and a one-line recommended action. Lead with hot-and-hard intersections.\n\n## Honesty\n\nProfile percentages are relative to the captured workload \u2014 say so; a different workload shifts the hot set. Respect `modeled_kinds`/`unmapped`: frames that mapped to no symbol are excluded, not zero-cost. Complexity is a syntactic estimate."
}