Rudder Performance Architecture Maintainer

Rudder Performance Architecture Maintainer

Use this skill when the user wants Rudder to become faster, more stable, or cleaner at the architecture boundary. The default result should be evidence-led optimization that preserves product contracts, not speculative tuning.

This skill covers two related classes of work:

• performance fixes: cache behavior, network waterfalls, repeated skeletons, slow queries, refetch loops, expensive renders, build/test slowness
• architecture fixes: unstable boundaries, oversized modules, duplicated data paths, unclear ownership, abstractions that make performance hard to reason about

Read references/optimization-checklist.md before doing non-trivial work with this skill. When the user asks for broad optimization or know-how capture, also read references/recent-thread-signals.md.

Use When

Use this skill for requests like:

• "为什么 dashboard 每次都骨架屏"
• "全局看看哪里可以做缓存加速"
• "这个页面/API 太慢，找一下瓶颈"
• "做一版系统性能优化"
• "数据量一大之后网页卡，给我优化前后的具体数值"
• "用 ZStudio 同等规模的数据在 DEV 里测一下"
• "这里是不是 query key / staleTime / invalidation 写错了"
• "架构上有什么热点文件或边界可以优化"
• "把这次性能优化 know how 沉淀成 skill"
• "分析一下最近的 thread 里有没有类似性能/架构任务"

Do Not Use When

Do not use this skill when the primary task is:

• data exists but a page shows missing, stale, sparse, or wrong data; use rudder-data-path-diagnostician-maintainer
• a large refactor where the user explicitly wants plan plus execution as the main deliverable; use architecture-refactor-driver-maintainer
• pure UI polish, spacing, copy, or visual QA
• release, package, installer, or Desktop startup recovery
• a single agent transcript or runtime failure investigation

If the task overlaps, choose the skill that matches the user's visible pain. For example, repeated skeleton loading after navigation belongs here; empty dashboard data belongs to data-path diagnosis.

Inputs

Capture or infer:

• affected surface, route, API, service, or subsystem
• user-visible symptom and expected improvement
• runtime and organization when live data is involved
• current cache, invalidation, polling, and freshness expectations
• constraints that must remain stable: API shape, schema, org scoping, runtime contracts, UI behavior
• acceptable validation depth for the blast radius

Evidence Ledger

Before proposing a fix, build a small evidence ledger. Keep it in your working notes unless it is useful to show the user.

| Observation | Evidence | Implication |
|---|---|---|
| Page remounts show skeleton | query key includes moving `to` timestamp | cache miss, not missing cache library |
| API is called by multiple cards | network trace or code search | candidate for shared query/prefetch |
| Service loads broad rows then filters | route/service/SQL inspection | push filter down or add index/test |

Evidence can come from code search, tests, API calls, browser/network traces, React Query Devtools-style reasoning, logs, SQL EXPLAIN, benchmarks, or profiling. Do not tune from screenshots alone.

Scale And Runtime Calibration

When live performance, production-shaped data, or user-visible slowness is part of the task, calibrate the runtime before interpreting numbers:

• call /api/health on the target server and record instanceId, localEnv, version/build fields, and any restartRequired signal
• prove whether the browser/dev server is running current code; restart or re-check health before treating browser evidence as current-branch proof
• use prod-local data only as a read-only sizing reference unless the user has explicitly authorized writes to that environment
• use dev or a disposable organization for pressure proof, implementation verification, and browser testing against current code
• if the user asks for a testable surface, seed or create a dev org at comparable scale before measuring; tiny fixtures cannot prove large-org behavior
• for transcript-heavy organizations, match payload shape as well as row counts: include large transcript, transcription, log, chat, heartbeat, and activity bodies when they are part of the real bottleneck
• if a full production clone fails because of seed tooling, memory, or data shape limits, report that as a blocker and substitute a synthetic scale-equivalent dev org with the limitation stated clearly

Separate evidence classes in notes and handoffs:

• prod-read-only baseline: current user data shape, sizing, and observed bottlenecks without mutation
• current-code dev proof: disposable data on the branch under test, suitable for before/after timing and browser verification
• synthetic pressure proof: generated row counts and heavy payloads that match the stress shape but are not a full clone

Workflow

1. Load Local Context

Read the minimum Rudder context needed for the surface:

• AGENTS.md
• doc/product/GOAL.md, doc/product/PRODUCT.md, and doc/product/README.md when the work changes behavior or architecture
• relevant UI page/hooks/API clients, server routes/services, shared contracts, DB schema, and nearby tests

Use rg first for call sites, query keys, endpoints, invalidation keys, and hot modules.

2. Mine Recent Threads When The Task Is Broad

When the user asks for global optimization, reusable know-how, or "recent thread" analysis, inspect recent Codex threads before editing code. Look for:

• prior performance scans and daily health checks
• repeated slow surfaces, large payloads, or unbounded list symptoms
• architecture decisions that moved work across UI/API/service boundaries
• reviewer-discovered blockers, especially privacy, transactionality, and org-scoping issues
• validation gaps caused by dev-server restarts, embedded Postgres bootstrap, or dirty shared worktrees

Use the thread evidence as hypotheses, not truth. Re-check the current code and runtime before implementing. Store durable patterns in references/recent-thread-signals.md or references/optimization-checklist.md.

3. Classify The Optimization

Pick the dominant class:

• cache-key-instability: keys include moving timestamps, object identity, or non-canonical filters
• freshness-policy-gap: stale time, refetch, polling, or invalidation does not match product freshness needs
• network-waterfall: serial requests could be shared, prefetched, batched, or moved server-side
• over-fetch: UI/API requests more data than the surface needs
• payload-overweight: item count is bounded but each row carries large transcript, log, activity, or nested hydration bodies
• server-hot-path: service aggregation, DB query, filesystem scan, or external process work is too expensive
• render-hot-path: React render, memoization, virtualization, or derived state work is too expensive
• boundary-erosion: architecture makes data ownership, caching, or performance contracts unclear
• validation-slowness: build/test/dev loop is slow because of avoidable setup, scope, or fixture cost
• frontend-race: a UI workflow depends on multiple ordered requests where the server should own atomicity

Name the first broken boundary. Downstream symptoms matter, but the first broken boundary is where fixes usually belong.

4. Trace The Path End To End

For UI performance, trace:

surface -> hook/query key -> API client -> route -> service -> DB/runtime source

For server/runtime performance, trace:

entrypoint -> facade/service -> query/process/filesystem -> response contract

Record:

• query key and parameter canonicalization
• staleTime, gcTime, placeholder data, polling, focus/reconnect behavior
• invalidation and mutation side effects
• endpoint path, request validators, and org scoping
• response shape and client-side filtering/aggregation
• latency, response bytes, item counts, and whether the response includes heavy transcript/log/activity bodies
• expensive loops, broad scans, N+1 calls, and repeated derived computation