BuzzbeeSCD/openchamber
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: refine agent skill guidance

Browse Source
This commit is contained in:
Bohdan Triapitsyn
2026-08-13 13:57:56 +03:00
parent d3011a6247
commit cc94c3c927
15 changed files with 212 additions and 248 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agents/skills/performance-engineering/SKILL.md
+8 -18
View File
@@ -11,6 +11,8 @@ Optimize the amount and frequency of work before optimizing individual operation
**Core principle:** Make expensive work structurally unnecessary. A fast inner function still freezes the app when called millions of times on the main thread.
Load `sync-state-invariants` when an optimization changes state authority, reconciliation, optimistic data, event ordering, cache lifecycle, or destructive cleanup. This skill owns measured cost; `sync-state-invariants` owns state correctness.
## Start With A Performance Contract
Define before editing:
@@ -27,6 +29,8 @@ Do not optimize against a toy fixture when the report provides production scale.
## Workflow
Complete the numbered workflow in order. An optimization is complete only when the exact measured scenario meets its budget and separate correctness checks preserve every applicable state, identity, layout, and lifecycle transition.
### 0. Trust The Measurement Before Trusting The Number
A measurement setup that is wrong produces clean, confident, wrong numbers, and
@@ -65,6 +69,8 @@ validity checks ran.
Do not infer a bottleneck from code appearance when a trace or counter can identify it.
Treat every proposed optimization as a hypothesis. Memoization, caches, indexes, workers, scheduling, retries, and lifecycle machinery must address an observed cost or failure in the measured path; “could be slow” or “might race” is not evidence. Keep only the smallest mechanism that meets the contract, except where an inherent security, data-loss, destructive-operation, or concurrency invariant requires proactive protection.
**Never accept an "after" without a "before" on the identical scenario and
build.** Measuring a fixed build against a remembered number, a different
scenario, or a nearby baseline proves nothing: the mechanism you changed may
@@ -193,6 +199,8 @@ Add a cache only when all are explicit:
- runtime/project/user isolation where identities can collide;
- proof that caching removes enough work to meet the budget.
Do not introduce a cache merely to make an abstraction reusable or prepare for future consumers. First prove repeated work in the real path; then place the cache with the narrowest owner and lifetime that can invalidate it correctly.
A cache inside an `O(consumers × entities × candidates)` loop is a mitigation, not automatically a complete fix.
## Repository Tooling
@@ -276,24 +284,6 @@ Ship a bounded cache-only or local mitigation under deadline pressure only when:
If the interaction remains above budget, do not call the mitigation the completed performance fix.
## Common Rationalizations
| Rationalization | Reality |
|---|---|
| "The helper is cheap" | Multiply it by events, entities, candidates, and consumers. |
| "No component rerendered" | Selectors and equality comparisons may still burn CPU. |
| "`useMemo` fixes it" | Memoization does not help when dependencies churn or consumers duplicate work. |
| "The cache made it 10× faster" | Compare the result with the interaction budget, not only the baseline. |
| "Projects are few" | Identify the dimension that is large and the dimensions multiplying it. |
| "Move it to a worker" | Moving waste changes responsiveness, not total cost or data correctness. |
| "Empty means nothing exists" | Empty after failure or partial loading is not authoritative absence. |
| "We can optimize later" | Add a scale regression now or the multiplier will return. |
| "The profile is clean" | Prove the instrument fired and the renderer was not throttled. A disabled instrument looks identical to a fast app. |
| "It is much faster now" | Against which baseline, on which build, in which scenario? Re-run the unchanged build. |
| "Most of the time is `(program)`" | The sampler cannot see native work. Read the timeline trace. |
| "It does not reproduce here" | Compare your scale to the reporter's on the dimension the code keys on. |
| "It cannot hurt to keep the change" | An unmeasured change is unvalidated complexity that hides the path from the next investigation. |
## Exit Checklist
- [ ] Measurement validity established: no throttling, instruments confirmed firing, workload comparable.