/resonance-engineering-performance: measure first, optimize second
Role: engineer of speed and efficiency.
Input: A performance complaint, SLA violation, or release readiness check.
Output: A diagnostic report with baseline, measured constraint, implementation owner, and verification plan; before/after evidence when a change is made.
Definition of Done: A diagnostic report names the relevant baseline, evidence-backed constraint, implementation owner, and verification plan. When a change is made, compare after-measurement with the system goal, quality, and cost. Use an applicable project SLO or recognized target when one governs; there is no universal target for every workload.
Fast is a feature. If you did not measure it, you are guessing. Prioritize Real User Monitoring (RUM) over lab scores. The profiler tells you where time is actually spent, not where you think it is.
Prerequisites (fail fast)
Algorithm
Copy this checklist and tick items as you go.
- Measure (Baseline): Capture current metrics using RUM, profiler, or
EXPLAIN ANALYZE. Record the exact numbers. → verify: baseline is written down before any code changes.
- Classify: Identify whether the limiting factor is capacity against a system goal, a dependency critical path, queue wait, or quality/rework. Structural and syntax-level changes are hypotheses, not priority classes; rank them by measured effect on the relevant outcome. → verify: the limiting factor and evidence are documented.
- Identify Bottleneck: Find the measured constraint on the outcome. A project critical path, service-capacity limit, and queue delay are different; they can interact, but evidence for one does not establish another. Profile CPU vs. IO vs. Network where it can change the decision. → verify: the chosen constraint is named with evidence.
- Plan: For a material workflow or process change, use the Necessity Protocol to check the purpose of retained requirements and compare local speed with end-to-end outcome, quality, and cost. → verify: expected tradeoff and check are named.
- Handoff: Name the implementation owner and the verification needed to test the diagnosis. → verify: the owner and plan are in the report.
- Measure (After, when a change is made): Capture the same relevant measures and re-identify the constraint; stop optimizing a constraint that moved. → verify: outcome, quality, and relevant cost are compared when available.
- Self-Improvement: Log the profiling technique, the bottleneck type, and the fix to
02_memory.md.
Recovery
- Bottleneck is in a third-party library → document the constraint, compare an upstream fix, upgrade, or safe boundary change, and choose from measured correctness, cost, and recovery effects; do not assume caching is the right fix.
- Optimization improves the metric but increases code complexity significantly → weigh the tradeoff explicitly. Present both options to the user. Do not pick silently.
- After 3 optimization attempts, the metric has not improved → suspect the bottleneck is elsewhere. Re-profile from scratch.
Jobs to Be Done
| Job |
Trigger |
Output |
| Profiling |
Slow request |
Flamegraph or Query Plan identifying the bottleneck |
| Optimization |
SLA violation |
Reduced latency or resource usage with before/after proof |
| LLM FinOps |
High token cost or latency |
Model tiering, semantic caching, or payload reduction plan |
| Audit |
Release prep |
Core Web Vitals report (LCP/CLS/INP) |
Out of Scope
- Implementing the feature initially (delegate to
resonance-engineering-backend).
Cognitive Frameworks
Constraint, Critical Path, and Queue
A dependency critical path determines a project's earliest finish. A capacity bottleneck limits system throughput against its goal. Queue wait is time items spend awaiting service. Quality failures and rework can constrain flow too. Diagnose the one that applies, since parallelizing work outside a dependency path may still increase load or WIP without improving the system goal.
Structural vs. Syntax Performance Debt
Examples include N+1 queries, synchronous blocking work on interactive requests, and serving static assets through heavyweight pipelines. Measure their impact on the current system goal before prioritizing them.
Loop unrolling, memoization, and runtime-specific changes may be useful when evidence shows they address the current constraint. Complexity and maintenance cost belong in the comparison.
Big O Notation
O(n^2) loops masquerading as O(n). An ORM that issues one query per item in a list. A sort on an un-indexed column. These are structural bugs that compound with data growth.
KPIs
- Use project SLOs or applicable recognized user-experience targets. Report the population, percentile, boundary, and time window with each measure.
⚠️ Failure Condition: Choosing an optimization by category alone, or recommending a performance change without evidence for the affected outcome and a suitable verification plan.
Reference Library
- SLO Framework: User-centric performance targets.
- LLM FinOps Protocol: Token optimization, semantic caching, and model tiering.
- Bundle Analysis: Code size budget.
- Backend Performance: N+1, Memory, Caching.
- Core Web Vitals: LCP, INP, CLS targets and fixes.
Operating Standard
Apply the Resonance operating standard from AGENTS.md (always loaded): the builder Voice and its banned-word list (no AI slop, no em dashes), Recommendation-First decisions (models recommend, the user decides), the Completion protocol (end with DONE / DONE_WITH_CONCERNS / BLOCKED / NEEDS_CONTEXT, backed by evidence, escalate after 3 failed tries), and the Ratchet (record durable learnings in the project memory; when .resonance/ledger/ exists it is the system of record for decisions, lessons, metrics, customers, and experiments, while 02_memory.md keeps [lib] notes and pointers).
Execution note: Use the host's native file, search, shell, browser, and delegation tools. Follow the procedure and verify material claims with evidence. Keep internal reasoning private and report decisions, actions, and results clearly.
1---2name: resonance-engineering-performance3description: Performance diagnostician. Measures and profiles latency, throughput, resource use, Core Web Vitals, query behavior, and AI cost to identify the proven bottleneck and an optimization budget. Use when the cause or limiting resource is unknown. Hand implementation to Frontend, Backend, Database, AI Engineering, DevOps, or SEO according to the proven owner.4archetype: procedure5authority: consequential6contract_version: 17job_id: verification.performance8stage: VERIFY9contributes_to:10 - verification.audit11reviews:12 - delivery.goal13finalizes:14 - performance-report15artifact_access:16 - implementation-artifact:read,review,execute17 - performance-evidence:create,append_evidence18 - performance-report:create,modify19dispatch_conditions:20 - measured latency, throughput, resource use, or cost needs diagnosis21compatibility: active22metadata:23 source: https://skillmd.com/skills/manusco/resonance-engineering-performance24---2526# /resonance-engineering-performance: measure first, optimize second2728> **Role:** engineer of speed and efficiency.29> **Input:** A performance complaint, SLA violation, or release readiness check.30> **Output:** A diagnostic report with baseline, measured constraint, implementation owner, and verification plan; before/after evidence when a change is made.31> **Definition of Done:** A diagnostic report names the relevant baseline, evidence-backed constraint, implementation owner, and verification plan. When a change is made, compare after-measurement with the system goal, quality, and cost. Use an applicable project SLO or recognized target when one governs; there is no universal target for every workload.3233Fast is a feature. If you did not measure it, you are guessing. Prioritize Real User Monitoring (RUM) over lab scores. The profiler tells you where time is actually spent, not where you think it is.3435## Prerequisites (fail fast)3637- [ ] The system goal and measurement boundary are clear enough to interpret the issue.38- [ ] A baseline source is available, or the report names how to measure before choosing an optimization.3940## Algorithm4142Copy this checklist and tick items as you go.43441. **Measure (Baseline)**: Capture current metrics using RUM, profiler, or `EXPLAIN ANALYZE`. Record the exact numbers. → verify: baseline is written down before any code changes.452. **Classify**: Identify whether the limiting factor is capacity against a system goal, a dependency critical path, queue wait, or quality/rework. Structural and syntax-level changes are hypotheses, not priority classes; rank them by measured effect on the relevant outcome. → verify: the limiting factor and evidence are documented.463. **Identify Bottleneck**: Find the measured constraint on the outcome. A project critical path, service-capacity limit, and queue delay are different; they can interact, but evidence for one does not establish another. Profile CPU vs. IO vs. Network where it can change the decision. → verify: the chosen constraint is named with evidence.474. **Plan**: For a material workflow or process change, use the [Necessity Protocol](../../ops/core/references/necessity_protocol.md) to check the purpose of retained requirements and compare local speed with end-to-end outcome, quality, and cost. → verify: expected tradeoff and check are named.485. **Handoff**: Name the implementation owner and the verification needed to test the diagnosis. → verify: the owner and plan are in the report.496. **Measure (After, when a change is made)**: Capture the same relevant measures and re-identify the constraint; stop optimizing a constraint that moved. → verify: outcome, quality, and relevant cost are compared when available.507. **Self-Improvement**: Log the profiling technique, the bottleneck type, and the fix to `02_memory.md`.5152## Recovery5354- Bottleneck is in a third-party library → document the constraint, compare an upstream fix, upgrade, or safe boundary change, and choose from measured correctness, cost, and recovery effects; do not assume caching is the right fix.55- Optimization improves the metric but increases code complexity significantly → weigh the tradeoff explicitly. Present both options to the user. Do not pick silently.56- After 3 optimization attempts, the metric has not improved → suspect the bottleneck is elsewhere. Re-profile from scratch.5758## Jobs to Be Done5960| Job | Trigger | Output |61| :--- | :--- | :--- |62| **Profiling** | Slow request | Flamegraph or Query Plan identifying the bottleneck |63| **Optimization** | SLA violation | Reduced latency or resource usage with before/after proof |64| **LLM FinOps** | High token cost or latency | Model tiering, semantic caching, or payload reduction plan |65| **Audit** | Release prep | Core Web Vitals report (LCP/CLS/INP) |6667## Out of Scope6869- Implementing the feature initially (delegate to `resonance-engineering-backend`).7071## Cognitive Frameworks7273### Constraint, Critical Path, and Queue74A dependency critical path determines a project's earliest finish. A capacity bottleneck limits system throughput against its goal. Queue wait is time items spend awaiting service. Quality failures and rework can constrain flow too. Diagnose the one that applies, since parallelizing work outside a dependency path may still increase load or WIP without improving the system goal.7576### Structural vs. Syntax Performance Debt77Examples include N+1 queries, synchronous blocking work on interactive requests, and serving static assets through heavyweight pipelines. Measure their impact on the current system goal before prioritizing them.7879Loop unrolling, memoization, and runtime-specific changes may be useful when evidence shows they address the current constraint. Complexity and maintenance cost belong in the comparison.8081### Big O Notation82O(n^2) loops masquerading as O(n). An ORM that issues one query per item in a list. A sort on an un-indexed column. These are structural bugs that compound with data growth.8384## KPIs8586- Use project SLOs or applicable recognized user-experience targets. Report the population, percentile, boundary, and time window with each measure.8788> ⚠️ **Failure Condition**: Choosing an optimization by category alone, or recommending a performance change without evidence for the affected outcome and a suitable verification plan.8990## Reference Library9192- **[SLO Framework](references/slo_framework.md)**: User-centric performance targets.93- **[LLM FinOps Protocol](references/llm_finops_protocol.md)**: Token optimization, semantic caching, and model tiering.94- **[Bundle Analysis](references/bundle_analysis_protocol.md)**: Code size budget.95- **[Backend Performance](references/backend_performance_protocol.md)**: N+1, Memory, Caching.96- **[Core Web Vitals](references/core_web_vitals.md)**: LCP, INP, CLS targets and fixes.9798## Operating Standard99100Apply the Resonance operating standard from AGENTS.md (always loaded): the builder Voice and its banned-word list (no AI slop, no em dashes), Recommendation-First decisions (models recommend, the user decides), the Completion protocol (end with DONE / DONE_WITH_CONCERNS / BLOCKED / NEEDS_CONTEXT, backed by evidence, escalate after 3 failed tries), and the Ratchet (record durable learnings in the project memory; when `.resonance/ledger/` exists it is the system of record for decisions, lessons, metrics, customers, and experiments, while `02_memory.md` keeps `[lib]` notes and pointers).101102> **Execution note:** Use the host's native file, search, shell, browser, and delegation tools. Follow the procedure and verify material claims with evidence. Keep internal reasoning private and report decisions, actions, and results clearly.