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
5. Choose The Smallest Correct Fix
Prefer behavior-preserving changes that make the real contract explicit:
- stabilize query keys before increasing
staleTime
- canonicalize date ranges, filters, and sort options at the boundary
- add explicit
limit, page, cursor, or preview contracts to broad navigation
list calls before optimizing rendering around unbounded data
- use
placeholderData, prefetch, or shared queries only when stale display is
acceptable and errors remain visible
- push filters to API/DB when the server owns the data contract
- batch or share requests when multiple components need the same data
- move multi-step UI writes into a narrow transactional API when partial success
creates broken product state
- introduce a facade when multiple consumers duplicate data-path or caching
semantics
- add indexes only with evidence and a migration path
- split hot files by responsibility when that reduces real coupling or clarifies
performance ownership
Avoid adding cache as a blanket cover for slow or incorrect code. Cache should
encode a freshness contract, not hide broken invalidation.
When replacing broad list responses with bounded previews, state the semantic
tradeoff. A preview endpoint can make navigation fast, but it is not equivalent
to a full aggregate unless the server computes the aggregate separately. If
offset pagination remains, name the residual skip/duplicate risk under
concurrent inserts and prefer cursor semantics for high-churn lists when scope
allows.
6. Add Regression Coverage
Match tests to the failure mode:
- cache-key stability: unit-test canonical range/filter helpers
- React Query behavior: component or hook tests for stable keys,
placeholderData, and invalidation behavior
- API/service hot path: route/service tests for filtering, org scoping, and
response shape
- DB query changes: integration tests around date/status/org boundaries
- user-visible workflow: E2E test when the repo rules require it
- multi-step writes: service/route tests for rollback and UI tests for the
single product action
Include at least one edge case when the optimization depends on dates, org
boundaries, permissions, async runtime state, or large data volume.
7. Validate And Commit
Run the narrow validation first, then the repo-appropriate baseline:
pnpm lint
pnpm -r typecheck
pnpm test:run
pnpm build
For visible UI changes, verify in a browser or desktop shell and include final
screenshots when useful. If a baseline command fails for unrelated reasons,
report the failing suite and keep the optimization commit scoped.
Per repo rules, commit and push completed skill, performance, or architecture
work. Stage only files for the current task when the worktree has unrelated
changes.
8. Record Know How
When a performance or architecture investigation produces a durable rule, add it
to references/optimization-checklist.md or a more specific future reference.
Do not record one-off local paths, private data, or transient timings as general
rules.
Decision Rules
- Measure or trace first; optimize second.
- Treat repeated skeletons as a cache-key/freshness problem until proven
otherwise.
- A changing
now, Date, random id, object literal, or unsorted filter inside
a query key is a cache miss factory.
- Do not persist org-scoped or sensitive data outside the intended cache
boundary.
- Keep API, DB, shared types, and UI contracts synchronized.
- Preserve organization scoping on every server-side optimization.
- Prefer one stable abstraction over duplicated ad hoc fixes across pages.
- Do not change product semantics during a performance refactor unless the user
asked for that change and tests cover it.
- Treat payload size as a first-class metric. JSON transfer, parse, hydration,
and render pressure can dominate even when SQL timing looks acceptable.
- Default navigation/list calls should have an explicit bounded contract:
limit, cursor/page, field projection, or a documented server aggregate.
- Do not claim current-code proof from a stale dev/prod server. Verify health,
branch/build freshness, and restart state before using browser numbers.
- Prefer synthetic scale-equivalent dev proof over unsafe prod mutation. Be
explicit when the proof is not a full production clone.
Output Shape
For diagnosis:
Root cause: <classification and concrete broken boundary>
Evidence:
- ...
Optimization:
- ...
Validation:
- ...
Follow-up opportunities:
- ...
For a quantified optimization report:
Runtime calibration:
- prod-read-only baseline: <server/version/org shape or not used>
- current-code dev proof: <server/version/org shape or not used>
Measurements:
| Surface/API | Env | Before latency | After latency | Delta | Before bytes | After bytes | Delta | Items before/after |
|---|---:|---:|---:|---:|---:|---:|---:|---:|
| ... | ... | ... | ... | ... | ... | ... | ... | ... |
Interpretation:
- ...
Residual risk:
- ...
For implementation handoff:
Changed:
- ...
Why it is faster/cleaner:
- ...
Validation:
- ...
Residual risk:
- ...
Safety
- Keep diagnosis read-only unless the user asked for implementation.
- Never run destructive cleanup or unscoped SQL as part of performance work.
- Do not broaden cache lifetime for sensitive, permissioned, or org-scoped data
without proving the key includes the correct scope.
- Do not remove loading, error, or empty states just to hide latency.
- Do not stage or revert unrelated user changes.
Validation Cases
See references/eval-cases.md for trigger tests and expected behavior.
1---2name: rudder-performance-architecture-maintainer3description: "Use when Rudder needs performance or architecture optimization: slow pages, skeleton loops, query cache misses, refetch storms, large-org over-fetching, payload budgets, expensive API/DB paths, hot files, boundaries, measurement, or ZStudio-scale proof."4metadata:5 source: https://skillmd.com/skills/undertone0809/rudder-performance-architecture-maintainer6---78# Rudder Performance Architecture Maintainer910Use this skill when the user wants Rudder to become faster, more stable, or11cleaner at the architecture boundary. The default result should be evidence-led12optimization that preserves product contracts, not speculative tuning.1314This skill covers two related classes of work:1516- performance fixes: cache behavior, network waterfalls, repeated skeletons,17 slow queries, refetch loops, expensive renders, build/test slowness18- architecture fixes: unstable boundaries, oversized modules, duplicated data19 paths, unclear ownership, abstractions that make performance hard to reason20 about2122Read `references/optimization-checklist.md` before doing non-trivial work with23this skill. When the user asks for broad optimization or know-how capture, also24read `references/recent-thread-signals.md`.2526## Use When2728Use this skill for requests like:2930- "为什么 dashboard 每次都骨架屏"31- "全局看看哪里可以做缓存加速"32- "这个页面/API 太慢,找一下瓶颈"33- "做一版系统性能优化"34- "数据量一大之后网页卡,给我优化前后的具体数值"35- "用 ZStudio 同等规模的数据在 DEV 里测一下"36- "这里是不是 query key / staleTime / invalidation 写错了"37- "架构上有什么热点文件或边界可以优化"38- "把这次性能优化 know how 沉淀成 skill"39- "分析一下最近的 thread 里有没有类似性能/架构任务"4041## Do Not Use When4243Do not use this skill when the primary task is:4445- data exists but a page shows missing, stale, sparse, or wrong data; use46 `rudder-data-path-diagnostician-maintainer`47- a large refactor where the user explicitly wants plan plus execution as the48 main deliverable; use `architecture-refactor-driver-maintainer`49- pure UI polish, spacing, copy, or visual QA50- release, package, installer, or Desktop startup recovery51- a single agent transcript or runtime failure investigation5253If the task overlaps, choose the skill that matches the user's visible pain. For54example, repeated skeleton loading after navigation belongs here; empty dashboard55data belongs to data-path diagnosis.5657## Inputs5859Capture or infer:6061- affected surface, route, API, service, or subsystem62- user-visible symptom and expected improvement63- runtime and organization when live data is involved64- current cache, invalidation, polling, and freshness expectations65- constraints that must remain stable: API shape, schema, org scoping, runtime66 contracts, UI behavior67- acceptable validation depth for the blast radius6869## Evidence Ledger7071Before proposing a fix, build a small evidence ledger. Keep it in your working72notes unless it is useful to show the user.7374```markdown75| Observation | Evidence | Implication |76|---|---|---|77| Page remounts show skeleton | query key includes moving `to` timestamp | cache miss, not missing cache library |78| API is called by multiple cards | network trace or code search | candidate for shared query/prefetch |79| Service loads broad rows then filters | route/service/SQL inspection | push filter down or add index/test |80```8182Evidence can come from code search, tests, API calls, browser/network traces,83React Query Devtools-style reasoning, logs, SQL `EXPLAIN`, benchmarks, or84profiling. Do not tune from screenshots alone.8586## Scale And Runtime Calibration8788When live performance, production-shaped data, or user-visible slowness is part89of the task, calibrate the runtime before interpreting numbers:9091- call `/api/health` on the target server and record `instanceId`, `localEnv`,92 version/build fields, and any `restartRequired` signal93- prove whether the browser/dev server is running current code; restart or94 re-check health before treating browser evidence as current-branch proof95- use prod-local data only as a read-only sizing reference unless the user has96 explicitly authorized writes to that environment97- use dev or a disposable organization for pressure proof, implementation98 verification, and browser testing against current code99- if the user asks for a testable surface, seed or create a dev org at100 comparable scale before measuring; tiny fixtures cannot prove large-org101 behavior102- for transcript-heavy organizations, match payload shape as well as row counts:103 include large transcript, transcription, log, chat, heartbeat, and activity104 bodies when they are part of the real bottleneck105- if a full production clone fails because of seed tooling, memory, or data106 shape limits, report that as a blocker and substitute a synthetic107 scale-equivalent dev org with the limitation stated clearly108109Separate evidence classes in notes and handoffs:110111- `prod-read-only baseline`: current user data shape, sizing, and observed112 bottlenecks without mutation113- `current-code dev proof`: disposable data on the branch under test, suitable114 for before/after timing and browser verification115- `synthetic pressure proof`: generated row counts and heavy payloads that match116 the stress shape but are not a full clone117118## Workflow119120### 1. Load Local Context121122Read the minimum Rudder context needed for the surface:123124- `AGENTS.md`125- `doc/product/GOAL.md`, `doc/product/PRODUCT.md`, and `doc/product/README.md`126 when the work changes behavior or architecture127- relevant UI page/hooks/API clients, server routes/services, shared contracts,128 DB schema, and nearby tests129130Use `rg` first for call sites, query keys, endpoints, invalidation keys, and131hot modules.132133### 2. Mine Recent Threads When The Task Is Broad134135When the user asks for global optimization, reusable know-how, or "recent136thread" analysis, inspect recent Codex threads before editing code. Look for:137138- prior performance scans and daily health checks139- repeated slow surfaces, large payloads, or unbounded list symptoms140- architecture decisions that moved work across UI/API/service boundaries141- reviewer-discovered blockers, especially privacy, transactionality, and142 org-scoping issues143- validation gaps caused by dev-server restarts, embedded Postgres bootstrap, or144 dirty shared worktrees145146Use the thread evidence as hypotheses, not truth. Re-check the current code and147runtime before implementing. Store durable patterns in148`references/recent-thread-signals.md` or `references/optimization-checklist.md`.149150### 3. Classify The Optimization151152Pick the dominant class:153154- `cache-key-instability`: keys include moving timestamps, object identity, or155 non-canonical filters156- `freshness-policy-gap`: stale time, refetch, polling, or invalidation does not157 match product freshness needs158- `network-waterfall`: serial requests could be shared, prefetched, batched, or159 moved server-side160- `over-fetch`: UI/API requests more data than the surface needs161- `payload-overweight`: item count is bounded but each row carries large162 transcript, log, activity, or nested hydration bodies163- `server-hot-path`: service aggregation, DB query, filesystem scan, or external164 process work is too expensive165- `render-hot-path`: React render, memoization, virtualization, or derived state166 work is too expensive167- `boundary-erosion`: architecture makes data ownership, caching, or performance168 contracts unclear169- `validation-slowness`: build/test/dev loop is slow because of avoidable setup,170 scope, or fixture cost171- `frontend-race`: a UI workflow depends on multiple ordered requests where the172 server should own atomicity173174Name the first broken boundary. Downstream symptoms matter, but the first broken175boundary is where fixes usually belong.176177### 4. Trace The Path End To End178179For UI performance, trace:180181```text182surface -> hook/query key -> API client -> route -> service -> DB/runtime source183```184185For server/runtime performance, trace:186187```text188entrypoint -> facade/service -> query/process/filesystem -> response contract189```190191Record:192193- query key and parameter canonicalization194- `staleTime`, `gcTime`, placeholder data, polling, focus/reconnect behavior195- invalidation and mutation side effects196- endpoint path, request validators, and org scoping197- response shape and client-side filtering/aggregation198- latency, response bytes, item counts, and whether the response includes heavy199 transcript/log/activity bodies200- expensive loops, broad scans, N+1 calls, and repeated derived computation201202### 5. Choose The Smallest Correct Fix203204Prefer behavior-preserving changes that make the real contract explicit:205206- stabilize query keys before increasing `staleTime`207- canonicalize date ranges, filters, and sort options at the boundary208- add explicit `limit`, page, cursor, or preview contracts to broad navigation209 list calls before optimizing rendering around unbounded data210- use `placeholderData`, prefetch, or shared queries only when stale display is211 acceptable and errors remain visible212- push filters to API/DB when the server owns the data contract213- batch or share requests when multiple components need the same data214- move multi-step UI writes into a narrow transactional API when partial success215 creates broken product state216- introduce a facade when multiple consumers duplicate data-path or caching217 semantics218- add indexes only with evidence and a migration path219- split hot files by responsibility when that reduces real coupling or clarifies220 performance ownership221222Avoid adding cache as a blanket cover for slow or incorrect code. Cache should223encode a freshness contract, not hide broken invalidation.224225When replacing broad list responses with bounded previews, state the semantic226tradeoff. A preview endpoint can make navigation fast, but it is not equivalent227to a full aggregate unless the server computes the aggregate separately. If228offset pagination remains, name the residual skip/duplicate risk under229concurrent inserts and prefer cursor semantics for high-churn lists when scope230allows.231232### 6. Add Regression Coverage233234Match tests to the failure mode:235236- cache-key stability: unit-test canonical range/filter helpers237- React Query behavior: component or hook tests for stable keys,238 `placeholderData`, and invalidation behavior239- API/service hot path: route/service tests for filtering, org scoping, and240 response shape241- DB query changes: integration tests around date/status/org boundaries242- user-visible workflow: E2E test when the repo rules require it243- multi-step writes: service/route tests for rollback and UI tests for the244 single product action245246Include at least one edge case when the optimization depends on dates, org247boundaries, permissions, async runtime state, or large data volume.248249### 7. Validate And Commit250251Run the narrow validation first, then the repo-appropriate baseline:252253```bash254pnpm lint255pnpm -r typecheck256pnpm test:run257pnpm build258```259260For visible UI changes, verify in a browser or desktop shell and include final261screenshots when useful. If a baseline command fails for unrelated reasons,262report the failing suite and keep the optimization commit scoped.263264Per repo rules, commit and push completed skill, performance, or architecture265work. Stage only files for the current task when the worktree has unrelated266changes.267268### 8. Record Know How269270When a performance or architecture investigation produces a durable rule, add it271to `references/optimization-checklist.md` or a more specific future reference.272Do not record one-off local paths, private data, or transient timings as general273rules.274275## Decision Rules276277- Measure or trace first; optimize second.278- Treat repeated skeletons as a cache-key/freshness problem until proven279 otherwise.280- A changing `now`, `Date`, random id, object literal, or unsorted filter inside281 a query key is a cache miss factory.282- Do not persist org-scoped or sensitive data outside the intended cache283 boundary.284- Keep API, DB, shared types, and UI contracts synchronized.285- Preserve organization scoping on every server-side optimization.286- Prefer one stable abstraction over duplicated ad hoc fixes across pages.287- Do not change product semantics during a performance refactor unless the user288 asked for that change and tests cover it.289- Treat payload size as a first-class metric. JSON transfer, parse, hydration,290 and render pressure can dominate even when SQL timing looks acceptable.291- Default navigation/list calls should have an explicit bounded contract:292 `limit`, cursor/page, field projection, or a documented server aggregate.293- Do not claim current-code proof from a stale dev/prod server. Verify health,294 branch/build freshness, and restart state before using browser numbers.295- Prefer synthetic scale-equivalent dev proof over unsafe prod mutation. Be296 explicit when the proof is not a full production clone.297298## Output Shape299300For diagnosis:301302```markdown303Root cause: <classification and concrete broken boundary>304305Evidence:306- ...307308Optimization:309- ...310311Validation:312- ...313314Follow-up opportunities:315- ...316```317318For a quantified optimization report:319320```markdown321Runtime calibration:322- prod-read-only baseline: <server/version/org shape or not used>323- current-code dev proof: <server/version/org shape or not used>324325Measurements:326| Surface/API | Env | Before latency | After latency | Delta | Before bytes | After bytes | Delta | Items before/after |327|---|---:|---:|---:|---:|---:|---:|---:|---:|328| ... | ... | ... | ... | ... | ... | ... | ... | ... |329330Interpretation:331- ...332333Residual risk:334- ...335```336337For implementation handoff:338339```markdown340Changed:341- ...342343Why it is faster/cleaner:344- ...345346Validation:347- ...348349Residual risk:350- ...351```352353## Safety354355- Keep diagnosis read-only unless the user asked for implementation.356- Never run destructive cleanup or unscoped SQL as part of performance work.357- Do not broaden cache lifetime for sensitive, permissioned, or org-scoped data358 without proving the key includes the correct scope.359- Do not remove loading, error, or empty states just to hide latency.360- Do not stage or revert unrelated user changes.361362## Validation Cases363364See `references/eval-cases.md` for trigger tests and expected behavior.