Live Perf

/live-perf — Live performance measurement and improvement

Exercise the feature to measure it, not to change it. Capture baselines. Evaluate measurements and audit GitLens conventions. Dispatch fix agents under three-tier discipline — never on speculation. Re-measure to confirm. Loop until no measured regressions and no convention violations remain.

Measure-first or don't touch. Speculation goes to open-questions, never to agents.

When to use vs other skills

Use /live-perf:

• Standalone when you want to perf-tune an existing feature without the full audit (render regressions, RPC chattiness, git-call storms, missing caching on hot paths)
• Delegated from /live-exercise Phase 7 as part of the ship-gate convergence loop

Do not use /live-perf:

• For speculative optimization of code that isn't measured slow
• As a substitute for /live-exercise when functionality or intent are in question (fix those first; perf-tune what works)
• For static code review without any live measurement

Prerequisites

• vscode-inspector MCP connected (auto-discovered via .mcp.json)
• Build currently passes (pnpm run build:quick)
• You can identify the scope (feature, lifecycle stage, user flow, diff, background op, or ad-hoc code path) — arbitrary "perf everything" invocations don't belong here

Scope / Exercise / Baseline — derive from the invocation

Every invocation varies along three axes. Derive each from the user's request; ask when ambiguous. The framework (three-tier discipline, convergence loop, exit) is invariant; only the axis values change.

Axis 1 — Scope (what to measure)

Axis 2 — Exercise strategy (how to drive it)

Axis 3 — Baseline strategy (what to compare against)

Default axis combinations

If ambiguous

Ask the user one question:

"What's the scope — a specific feature, a lifecycle stage (activation/startup), a cross-feature user flow, the diff on this branch, or a background operation?"

Then infer exercise + baseline from the scope choice and the defaults above.

Measurement categories — what you measure (independent of scope)

Regardless of scope, every measurement pass covers these four categories. Skip only when clearly not applicable (document why if skipped).

Default when running on Opus: delegate the raw measurement capture to the inspector-driver subagent (Sonnet 5) — Agent({ subagent_type: "inspector-driver", model: "sonnet", prompt: <the exact probes: performance.now() deltas, updateComplete timings, notification counts, N samples> }). Sonnet captured a disciplined updateComplete measurement at parity in a smoke test. You keep the three-tier classification (Measured/Convention/Speculation) and all fix decisions — the driver only returns numbers. Cold-launch/startup metrics and baseline↔post-fix comparisons: have the driver reuse the instance you launched, or run those cold samples yourself, per the reset rule below.

1. Render / webview perf

What to measure:

• Initial render + hydration time per webview (from launch / refresh to Lit updateComplete)
• Re-render frequency during state transitions (Lit component updated() counts)
• Layout thrash / forced reflows (Performance API layout-shift, long tasks)
• Animation / transition smoothness (composited vs main-thread, frame drops)

Tools: evaluate_in_webview with performance.now(), PerformanceObserver, performance.getEntriesByType("measure"), document.querySelector('...').updateComplete for Lit.

Multi-webview perf: With 2+ webviews open, untargeted evaluate_in_webview silently runs in the first one — usually the wrong one. Run list_webviews first, then scope every measurement with webview_url/webview_index (full targeting reference in /live-inspect).

2. RPC / data transfer

What to measure:

• Notifications fired per user action (count by type)
• Payload size per notification (large arrays flagged)
• N+1 patterns (request loops instead of batched fetches)
• Round-trip count per flow

Tools: instrument the RPC layer via evaluate_in_webview to wrap rpcController/rpcClient under src/webviews/apps/shared/rpc/. read_logs for RpcHost/RpcLogger traffic in src/system/rpc/logger.ts. For extension host side, read_logs with pattern matching on the notification names.

3. Hot-path code audit

What to audit (code-level, not measured):

• Uncached repeated operations (multiple awaits to the same getter / provider method)
• Missing @memoize on pure, frequently-called getters
• Missing GitCache / PromiseCache usage on git-derived data
• Serialized awaits where Promise.all fits
• Missing debounce / throttle on frequent events (scroll, resize, input, mousemove)

Audit the code under scope — a feature's source, the diff of a branch, the activation path, etc. Use Read and Grep.

4. Git calls

What to measure / audit (git cost is spawn-heavy, not execution-heavy):

• Redundant git commands across components (the same git log/git status fired multiple times for one user action)
• Unbatched parsing (one piece of info per command instead of parsing multiple from a single output)
• Missing cache use on repeat callers (same git result re-fetched)
• Git-triggered refresh storms (one external change triggering N refreshes)

Tools: read_logs with pattern matching on git command logs (GitLens logs git calls with debug logging). Code audit for patterns in packages/git-cli/src/providers/. evaluate on the extension host to count command invocations over a user-action window.

Three-tier discipline

Every finding is classified into one of three tiers. The tier determines whether agents dispatch and under what rules.

Rules:

• Measure-first for Measured-tier. Capture baseline BEFORE touching anything. Capture post-fix measurement AFTER. If post-fix doesn't improve vs baseline, revert and re-investigate — don't ship "fixes" that aren't fixes.
• Convention-tier can dispatch on audit alone. Missing @memoize on a repeated pure getter IS a bug — you don't need to measure the savings to justify the fix.
• Speculation NEVER dispatches. If you can't measure it and it's not a convention violation, it's an open question for the user.

The loop

1. Derive scope / exercise / baseline

Pick an axis value for each of Scope, Exercise, and Baseline — from the user's invocation, the /live-exercise handoff, or the default combinations table above. If any axis is ambiguous, ask the user the single scope question above and infer the rest from defaults.

• When invoked from /live-exercise Phase 7: scope is whatever live-exercise was run against; exercise defaults to user-like; baseline defaults to absolute + averaged.
• When invoked standalone: derive from the user's request. "Startup," "feature X," "this branch," "background," "large repo" all map cleanly via the defaults table.
• Read goals.md if present for stated perf requirements (thresholds, budgets). These become Axis-3 targets.

Record the chosen axes at the top of baseline.md so the intent is auditable.

2. Baseline — drive the exercise (do not change code)

launch VS Code if not already running. For the chosen Exercise strategy:

1. Enable relevant logging / instrumentation (git debug log, RPC logger, PerformanceObserver).

2. Drive the exercise according to Axis 2:

   • User-like: click/scroll/type through the flow, repeat per baseline strategy
   • Programmatic: execute_command, event dispatch, or evaluate — repeat per baseline strategy
   • Ambient: leave VS Code running, observe over a time window (e.g., 2–5 minutes), don't drive it
   • Cold launch: teardown + relaunch for each run (startup mode needs cold state every time)
   • Stress: rapid repeat, concurrent, or large-data variant per the baseline's paired-measurement need

3. Capture measurements for each category that applies:

   • Render: evaluate_in_webview with performance.measure, updateComplete timing
   • RPC: log-parsed notification counts + payload sizes
   • Git: read_logs with git command pattern, counted over the exercise window
   • Hot-path: N/A (audit only, not measured)

4. Record baseline numbers in .work/live/<feature>-perf/baseline.md:

   # <Feature> — Perf Baseline
   
   Recorded: <ISO date>
   
   ## Render
   
   - Home webview hydration: 220ms (avg 5 runs)
   - Repeat render on branch switch: 85ms
   
   ## RPC
   
   - Notifications per branch switch: 12
   - `DidChangeRepositoriesNotification` payload: 48KB
   
   ## Git
   
   - Commands per branch switch: 7 (3x `git log`, 2x `git status`, 2x `git rev-parse`)
   

3. Evaluate — measurements + conventions audit

Compare measurements against:

• Thresholds (general guidance: webview hydration <150ms; webview refresh <100ms; >3 git calls for a single user action is suspicious; >5 notifications/action is suspicious)
• Prior baseline if one exists (.work/live/<feature>-perf/baseline.md from a previous run, or git history)
• Stated requirements in goals.md

Separately, audit the code (Read + Grep) for convention violations in the scope categories above.

4. Compile findings

Write .work/live/<feature>-perf/findings.md:

# <Feature> — Perf Findings

## Status

| ID     | Tier        | Category | Title                                     | Status | Baseline → Target |
| ------ | ----------- | -------- | ----------------------------------------- | ------ | ----------------- |
| I1-PR1 | Measured    | Render   | Home hydration 220ms (threshold 150ms)    | open   | 220 → <150        |
| I1-PC1 | Convention  | Hot-path | Missing @memoize on GitProvider.getBranch | open   | —                 |
| I1-PS1 | Speculation | Git      | Could batch log+status into one spawn     | see Q1 | —                 |

## 🔴 Measured (PR)

### I1-PR1 — Home hydration exceeds threshold

- **Baseline**: 220ms avg over 5 runs (fresh launch → `gl-home-app.updateComplete`)
- **Target**: <150ms
- **Hypothesis**: RPC warmup serialized; Lit templates heavy
- **Fix direction**: check if Home state can be prefetched / cached; audit Lit template for unused imports

## 🟡 Convention (PC)

### I1-PC1 — Missing @memoize on getBranch

- **File**: `packages/git-cli/src/providers/branches.ts:L88`
- **Convention**: pure getter called in render paths → must be @memoize'd
- **Evidence**: grep shows 7 call sites, 3 in render paths
- **Fix**: add `@memoize()` decorator

## ⚪ Speculation (PS)

### I1-PS1 — Could batch log+status into one spawn

- Moved to `open-questions.md` Q1

Write .work/live/<feature>-perf/open-questions.md for speculation items:

## Q1. Batch log + status for branch switch?

Currently 2 git spawns per branch switch. Could batch via combined `git log --name-status` parsing.

**Pros**: saves ~30ms/switch (~estimated, not measured)
**Cons**: touches parser layer, risk of parser bugs, speculative savings

**Recommendation**: file for later unless branch-switch latency is user-visible bad

5. Dispatch fix agents (Measured + Conventions only)

For each Measured finding AND each Convention finding:

• Group related fixes (e.g. all @memoize additions in one file → one agent)
• Cap at 5–6 concurrent
• Each agent prompt MUST include:
  • Exact file paths + line numbers
  • Tier (Measured or Convention)
  • For Measured: the baseline number AND the target. Agent must verify improvement via live re-measurement, not assumption.
  • For Convention: the convention being violated + the canonical pattern to apply
  • Verification command (pnpm run build:quick)
  • Project conventions (.js imports, no barrel files, no drive-by refactors, no --no-verify)
  • Explicit out-of-scope

Never dispatch for Speculation. Those are the user's call via open-questions.md.

Subagents must re-measure, not assume

When dispatching a Measured-tier fix, the agent prompt MUST tell the subagent to re-exercise the feature and re-capture the measurement after the fix. Example:

Fix the Home hydration baseline of 220ms by [approach]. After the fix, rebuild with pnpm run build:quick, relaunch VS Code via the vscode-inspector MCP, re-exercise fresh-launch → Home → updateComplete 5 times, capture the new average. Report the baseline → post-fix numbers. If post-fix >= baseline, revert and report.

6. Verify & loop

When agents complete:

1. pnpm run build:quick. Fix any breakage.
2. git diff after every agent — trust nothing blindly.
3. Reset for re-measurement. Cold-launch/startup metrics and every baseline↔post-fix comparison need a full teardown + relaunch — cached state ruins baselines. For warm-operation samples (render/RPC/git) within one build you may reuse the running instance and re-trigger, but a code change always means a fresh build + relaunch before the post-fix number counts.
4. Re-exercise the feature and re-capture measurements for everything the agents touched.
5. Update findings.md:
   • If post-fix measurement improved past target → ✅ Measured
   • If post-fix didn't improve → keep open, re-investigate (don't ship a "fix" that isn't)
   • If post-fix regressed another metric → new finding in next iteration
6. If convention fixes landed → re-audit to confirm the pattern is now consistent.
7. Loop to step 2 if any findings remain or new ones surfaced.

7. Exit

Exit when:

• All Measured findings have verified improvement OR have been reclassified (moved to open-questions with rationale)
• All Convention findings are fixed
• Speculation items are filed in open-questions for user review
• A fresh baseline re-capture shows no new regressions

When invoked from /live-exercise Phase 7: upon exit, return control to live-exercise. If this pass produced changes, live-exercise loops back to its Phase 5. Speculation items surface to the user alongside live-exercise's open-questions.md.

Pitfalls

Red flags — pause the loop

• You're about to dispatch a fix without a captured baseline
• Agent reported "improvement" but git diff shows only rewrites, no measurement logic
• You haven't teardown + relaunched between baseline and post-fix measurement
• Post-fix measurement is within noise (<10%) of baseline; you're "winning" on variance
• A speculation item has been sitting open for 3+ iterations — escalate to user, don't quietly dispatch
• You're about to apply a convention fix to code that isn't actually on a hot path

Tripwires for "skipping measurement"

Any of these in your reasoning = stop and measure first.

• "This is obviously faster"
• "Standard optimization pattern"
• "Everyone caches this kind of thing"
• "Looks like a hot path"
• "Won't hurt to add @memoize"
• "Agent said it improved"

Measured-tier requires a number. Convention-tier requires a pattern match. Neither allows "obvious."

Rationalizations to resist

Before declaring "live-perf complete"

Before reporting, confirm you have:

1. Captured a documented baseline for every metric you're acting on
2. Dispatched only Measured + Convention findings — speculation stays in open-questions
3. Verified post-fix measurements via re-exercise + re-capture (not agent self-report)
4. git diff'd every agent's work — no silent regressions
5. Teardown + relaunched between baseline and post-fix measurements
6. Surfaced open-questions.md to the user for speculation items
7. If invoked from /live-exercise: returned control after exit, with changes (if any) triggering the parent's loop

Output artifacts

• .work/live/<feature>-perf/baseline.md — captured measurement baselines (per iteration)
• .work/live/<feature>-perf/findings.md — tier-classified findings with baseline → post-fix numbers
• .work/live/<feature>-perf/open-questions.md — speculation items for user review
• Clean working tree with targeted commits / staged changes
• Post-fix measurements documenting the actual improvement (not just "LGTM")

Related skills

REQUIRED BACKGROUND:

• /live-inspect — primitive MCP tool reference (evaluate_in_webview, read_logs, evaluate, read_console)

Related:

• /live-exercise — invokes this skill from Phase 7; use it first for functional/intent issues
• /live-pair — interactive counterpart; delegates here on "this feels slow" signals
• /simplify — code-quality cleanup after perf fixes
• /deep-review — static correctness tracing; catches perf bugs that don't surface under current load