perf-investigate

Perf / Leak Investigation

Project context: Values in angle brackets below (e.g. <scheme>, <JIRA_KEY>, <flag-key-enum>) are resolved at runtime — detect them from the project (xcodebuild -list -json for the scheme, git/gh for repo & owner, the branch name for the Jira key, a codebase search for flag/font files), or ask if they cannot be inferred. This plugin ships no per-project config.

Drive an iOS performance or memory-leak investigation on using Memory Graph + Time Profiler. Enforce data-before-architecture and stacked PRs.

Usage

/perf-investigate <symptom or <JIRA_KEY>-XXXX>

Examples:

/perf-investigate <Feature> place-details opens are slow after 15 cycles
/perf-investigate <JIRA_KEY>-XXXX
/perf-investigate Explore tab leaks BSPlaceDetailVMV3

Triggers

Run this skill when the user mentions any of: "perf", "lento", "slow", "leak", "memory", "vazamento", "TTI", "hang", "jank", "frame drop", "spin", "freezou", "trava".

Hard rules (do not skip)

1. No architectural change before measurement. Reject hypotheses framed in architectural terms ("the wrapper is wrong", "the navigation pattern leaks") until the user provides a .memgraph (for retention) or a .trace (for TTI/jank).
2. Memory Graph (.memgraph) for retain cycles, NOT xctrace --template Leaks --attach. The latter fails silently with libmalloc not initialized. See reference_ios_leak_tooling.md.
3. Time Profiler with --attach works for hangs and CPU sampling. Use it for TTI/slowness investigations.
4. Compare to a fluid baseline tab. Pick a known-fluid feature in your app as the baseline; capture both the suspect and baseline in the same session.
5. One PR per logical fix. If the investigation produces 2+ fixes, use stacked PRs — see commit-and-pr skill.

Workflow

Phase 1 — Triage (no code yet)

1. Restate the symptom in observable terms (e.g., "after 15 opens, next open takes 6s" not "the wishlist is slow").
2. Decide the right tool:
   • "X is retained / leaking / accumulating" → Memory Graph (Tool 2 in the tooling memory).
   • "X is slow / hangs / janky" → Time Profiler (Tool 3 in the tooling memory).
   • "Memory grows over time without leaks" → Allocations Mark-Heap (Instruments GUI only — fall back to user).
3. Ask the user to capture the right artifact and save to ~/Desktop/<descriptive-name>.{memgraph,trace}. Provide the exact xctrace command if Time Profiler is needed.
4. Also ask for a baseline capture from a comparable fluid tab (usually Explore) when relevant.