Ade Autoresearch

ade-autoresearch

A Karpathy-style autoresearch loop for ADE perf. You (the agent) ARE the loop runner — there is no hidden script. Follow this algorithm exactly.

Inputs

• <tab>: the tab to optimize. Must be one of: boot, lanes, prs, work, files, run, graph, review, history, automations, cto, settings. (boot = cold launch + welcome + project open + remote runtime + iOS pairing — the "main ADE screen" surface above any specific tab.)
• <perf-pass-dir>: throwaway git repo path. Defaults to /Users/admin/Projects/perf pass (note the space — quote it). Must exist, must be a git repo, must have a perf-pass-seed tag (or you create one on first run). Override via ADE_PERF_PASS_DIR env var.

Real UI audit is the primary loop

The job is to find what a person actually feels in the tab. Do not predefine a fixed deterministic scenario suite and mistake that for the audit. Build the measurement plan from the live UI, source, and perf-pass repo; then create whatever repeatable probes, scripts, seeded repo states, or tests are needed to show load-time, CPU, heap, IPC, render, and interaction deltas for the surfaces the user actually exercises.

Use this order:

1. Warm launch the real Electron UI on the target tab and keep it open while auditing:

   NO_DEVTOOLS=1 ADE_DISABLE_LOCAL_RUNTIME_DAEMON=1 ADE_LOCAL_RUNTIME_FALLBACK=1 ADE_MODEL_OVERRIDE=gpt-5-codex \
     node scripts/perf-launch.mjs --tab <tab> --run-id <tab>-ui-audit-$(date +%Y%m%d-%H%M)

   Confirm the Electron surface is on the requested tab. The visible active tab must match <tab>; do not audit a related embedded surface from another tab.

2. Build an action inventory from the visible UI and source. Start with the tab's actual first screen, then cover every safe user action, subpane, menu, picker, dialog, mode switch, list interaction, empty state, error/preflight state, expand/minimize/fullscreen state, keyboard/search/filter path, and tab-specific destructive/external preflight. For destructive or externally visible actions, open and measure the prompt/preflight unless the user has explicitly allowed final execution.

   The inventory must be tab-derived. For example, a Work pass should cover Work sidebar/session list, chat/CLI/shell start surfaces, session tabs/grid/layout controls, running/ended session actions, model/attachment/command/parallel pickers, terminal/chat panes, context menus, filters/search, and ADE tools drawers because those are Work-tab surfaces. A Lanes pass should cover lane list, stack graph, lane dialogs, Git Actions, and lane Work panes because those are Lanes-tab surfaces.

   Do not claim complete coverage until the inventory itself says every row is measured, prompt-only, external-skip, or explicitly deferred with a reason. A handful of representative clicks is a partial smoke pass, not an audit. If an action matrix already exists for the tab, update that matrix as evidence arrives instead of replacing it with narrative notes.

   Treat the matrix as the work queue. Pick the next unresolved action/state, drive that exact UI path, record evidence, then either promote the row or mark why it needs a fixture, sandbox, prompt, or external dependency. When a row exposes slowness, churn, overflow, broken behavior, or missing accessibility, make one targeted product change, re-drive that same row, and only then move to the next row.

3. Mark each UI segment in the perf log before and after exercising it:

   window.ade.perf.recordEvent({ kind: "manualStep", ts: Date.now(), name: "git-actions-stage", phase: "start" });
   // drive the visible UI
   window.ade.perf.recordEvent({ kind: "manualStep", ts: Date.now(), name: "git-actions-stage", phase: "end" });

   Segment names should describe the workflow, not the implementation detail.

4. Use direct IPC only for setup, cleanup, and analysis. It is fine to create fixture data, reset a throwaway repo, query status, or extract metrics through IPC/shell. Do not replace a UI audit action with window.ade.* unless the UI is genuinely impossible to drive; if you must, say so in the run notes.

5. Create UI-derived probes after findings. If existing scenarios cover a surface, you may run them. If they do not, write a tab-specific probe, scenario, fixture, or test that reproduces the measured workflow against the perf-pass repo. The probe is evidence, not a product requirement: it exists to quantify a real UI bottleneck and compare before/after behavior.

Setup (do once at start of run)

1. Read prior wins at .agents/skills/ade-perf-<tab>/SKILL.md if it exists. These are optional best-practice notes from earlier audits, not prerequisites. If no per-tab skill exists, derive the checklist from the tab UI and source and create the per-tab skill only during codification after you have measured real behavior.
2. Inspect existing perf probes under apps/desktop/src/renderer/perf/scenarios/, scripts, and tab tests. Reuse what matches the tab, but do not treat missing or incomplete scenarios as a blocker and do not let scenario availability define the work. It is acceptable to add new tab-specific scenarios/probes when they help quantify a real UI workflow.
3. Verify perf-pass repo exists, has a seed tag, and can exercise real GitHub paths when needed:

   scripts/reset-perf-pass.sh

   Refuse to start if perf-pass doesn't exist. If the tab uses GitHub behavior, publish the repo as a private perf-pass remote before measuring push/pull/fetch UI.
4. Create a working branch off main:

   git checkout -b autoresearch/<tab>-$(date +%Y%m%d-%H%M)

5. Set the model override for all in-ADE AI activity: export ADE_MODEL_OVERRIDE=gpt-5-codex (or another GPT/Codex model id available in ADE). Don't touch this during the run.

Baseline (iteration 0)

Start with the real UI inventory. The baseline is complete when every safe tab surface has been exercised or explicitly marked unsafe/external/destructive, and each measured segment has corresponding perf evidence.

For each important workflow, capture at least one of:

• A real UI perf-launch run with manualStep markers in ~/.ade/perf-runs/<runId>/events.jsonl
• A purpose-built probe or scenario that drives the workflow against the perf-pass repo and writes summary.json / events.jsonl
• A focused unit/component/integration test that reproduces the expensive derive, mount, or IPC behavior
• A shell/IPC setup script only for fixture creation and cleanup

Record baseline_metrics as a small table, not a single mandatory fitness score. Include the metrics that matter to the surface: route/load time, segment duration, main CPU p95, renderer CPU or long tasks, heap growth, IPC count/p95, render-on-scroll time, or panel mount cost. If an existing scenario reports a fitness score, keep it as one data point; do not let it override real UI evidence.

Then analyze events.jsonl by manualStep segment. Record the worst UI segment, the slow IPC channels inside it, and whether the cost is expected work (for example network push/fetch) or avoidable tab work.

Tag the baseline commit:

git tag perf-baseline-<tab>-$(date +%Y%m%d)

Iteration loop

Stop conditions: no measurable improvement on the current bottleneck for 10 consecutive attempts OR user kills the run OR 50 iterations OR 4 hours wall-clock.

For each iteration:

1. Analyze

• Read the latest real-UI events.jsonl, probe outputs, scenario summaries, and focused test results.
• Pick the #1 bottleneck: the avoidable cost that appears in real UI segments or repeatable probes. Tie-break by user-visible workflow first, then reproducibility and metric severity.
• Common bottleneck categories:
  • Slow IPC channel: a channel in summary.ipc.slowChannels with p95 ≥ 120ms
  • Long task spam: webVitals.longTaskCount > 5 per minute
  • Memory growth: process.rendererHeapGrowthMB > 10 over a measured workflow
  • Render-on-scroll cost: marks.scroll.* p95 high
  • Route transition cost: marks.nav.* or marks.switch.* p95 high
  • Main CPU: process.mainCpuPercentP95 > 30 during idle or panel-open probes → background pollers
• UI segment waste: heavy refreshes, duplicate mounted panes, hidden pollers, repeated global status checks, or expensive dialog prefetches that are not needed for the action the user took
• Read the code that owns the bottleneck. Form a hypothesis.

2. Propose ONE change

Legal moves (examples, not a complete list):

• Memoize a hot selector with useMemo / useCallback
• Batch IPC calls (collapse N independent invokes into one)
• Debounce / throttle a poller
• Virtualize a long list (@tanstack/react-virtual or similar)
• Lazy-load a heavy component (React.lazy)
• Replace O(n²) work with a Map lookup
• Hoist a stable callback out of render
• Skip re-renders with React.memo + stable props
• Move work off the render thread (requestIdleCallback, microtask deferral)
• Replace a polling interval with an event-driven subscription
• Cache an expensive derive (only invalidate on deps change)

Forbidden moves:

• Editing anything under apps/desktop/src/main/services/perf/**
• Editing metrics plumbing under apps/desktop/src/renderer/perf/harness/**, apps/desktop/src/renderer/perf/markers.ts, or apps/desktop/src/renderer/perf/webVitals.ts to make results look better
• Editing scripts/run-perf-scenario.mjs or scripts/reset-perf-pass.sh to weaken measurement or setup
• Editing test files to make them pass
• Disabling polling/sync features outright (only debounce/throttle)
• Removing UI features or hiding elements to bypass measured workflows
• Changing metric weights, summaries, or existing probes to mask a regression

Allowed measurement moves:

• Add new tab-specific scenarios/probes under apps/desktop/src/renderer/perf/scenarios/ when they drive a real UI-derived workflow.
• Add scripts under scripts/ or tests under the touched feature area to seed the perf-pass repo or reproduce an expensive UI path.
• Expand a probe to cover a newly discovered tab surface, provided it remains honest about what it measures.