SAYLOR The result you are building
Finished Result:
A performance profile and release gate that uses field plus lab evidence, isolates network/server/render/script/media/font causes, improves LCP/INP/CLS without breaking function, and monitors regressions by device and route.
Use this guide when
- A site feels slow, shifts during load, or responds late to interaction.
- A redesign, analytics tag, image, font, or third-party script changes performance.
- You need user-centered evidence instead of one desktop speed score.
Do not use it as a substitute for
- Optimizing only a synthetic homepage run on a fast machine.
- Removing accessibility, security, consent, or essential function merely to improve a score.
Before you change anything
Collect these items first. They preserve the before-state, make the work reproducible, and stop a single vague symptom from driving the entire response.
- Critical routes and user journeys, business conversions, devices, networks, locations, and browsers.
- Real-user LCP/INP/CLS and supporting navigation/resource/long-task data by slice.
- Lab waterfall, trace, filmstrip, CPU/network profile, server timing, and cache status.
- Release, CDN, HTML, CSS, JS, image, font, third-party, and feature-flag versions.
- Performance budgets, functional/accessibility checks, canary, and rollback evidence.
Stop Before Proceeding:
Stop broad optimization when no representative field baseline exists or when a proposed change breaks accessibility, security, consent, correctness, or a critical user journey.
Understand the system before fixing it
Observe before mutating Capture state, logs, versions, ownership, and dependency health before restarting, reinstalling, deleting, or rotating anything.
Recovery must be exercised A backup, rollback command, or spare endpoint is only a claim until a controlled restore or failover test proves it works.
Field and lab data serve different purposes Field data tells who is affected; lab traces reproduce and isolate. Neither alone proves the whole population or the cause.
The largest byte is not always the bottleneck Connection setup, server wait, discovery delay, render blocking, main-thread work, interaction handlers, and layout dependencies can dominate.
Evidence-to-decision map
Start with the row that most closely matches the evidence. The first test isolates a layer; it is not permission to
make every available change.
Evidence Likely layer First decisive check What the result means
LCP slow, server fast Discovery/ren Trace LCP resource request Hero resource is discovered late, low priority, blocked, or
der start and priority rendered after JS.
INP poor on Main Profile long tasks and Script execution, layout, or handler work blocks response.
mid-range phones thread/handler interaction phases
CLS occurs after load Dynamic Record layout-shift sources Unsized media, injected content, font swap, or late component
layout during interaction changes geometry.
Lab fast, field slow Population/cac Slice field data by Lab conditions miss real devices, geography, cold cache, or third
he device/network/route/cache parties.
Deploy regression Bundle/feature Diff route assets and feature Shared or route-specific code changed the critical path.
only on one route flagsStep-by-step procedure
Work in order and retain the output from each step. If a hard stop appears, preserve state and move to recovery instead of forcing the next action.
01 Define representative journeys and budgets Why: A precise boundary prevents a plausible fix from solving the wrong problem.
Do: Choose key routes/actions, device/network/browser slices, conversion outcome, and performance/accessibility/function budgets. Use user-centric percentile targets.
Read the result: Budget matches the real audience and business task.
Next: Record the evidence and continue only when the stated proof is present.
02 Capture field and lab baseline Why: Symptoms are not enough; a baseline preserves the evidence needed to isolate the failing layer.
Do: Collect real-user vitals and supporting diagnostics, then reproduce representative slow slices with waterfall, trace, filmstrip, CPU/network, and server timing.
Read the result: The affected population and repeatable scenario are known.
Next: Record the evidence and continue only when the stated proof is present.
03 Identify the critical path Why: Inconsistent inputs create false differences and make later comparisons unreliable.
Do: Map DNS/TLS, TTFB, HTML, preload/discovery, blocking CSS/JS, LCP resource, font/media, hydration, long tasks, interactions, and layout shifts.
Read the result: One or more measured bottlenecks explain the user metric.
Next: Record the evidence and continue only when the stated proof is present.
04 Fix the narrow cause Why: A decisive test reduces trial-and-error and limits unnecessary change.
Do: Prioritize/cache the LCP resource, optimize server/query/CDN, reduce/split/defer script, reserve dimensions, control fonts and third parties, or simplify interaction work as evidence supports.
Read the result: Trace shows the targeted phase improved without moving delay elsewhere.
Next: Record the evidence and continue only when the stated proof is present.
Procedure continued 05 Protect correctness and inclusion Why: The smallest reversible correction lowers the blast radius while preserving a recovery path.
Do: Re-run functional, responsive, accessibility, consent, auth, analytics, and content checks across key browsers and devices.
Read the result: Performance gain does not remove required behavior or introduce shift/error.
Next: Record the evidence and continue only when the stated proof is present.
06 Canary with real-user monitoring Why: The happy path cannot expose replay, timeout, malformed-input, authority, or dependency failures.
Do: Release to a slice, annotate version, compare matched cohorts and error/conversion signals, and roll back on budget breach.
Read the result: Field percentiles improve for the target slice without adjacent regression.
Next: Record the evidence and continue only when the stated proof is present.
07 Enforce ongoing budgets Why: A result is not complete until it remains observable and repeatable after the immediate fix.
Do: Gate asset sizes, critical requests, long tasks, image dimensions, and lab checks in CI; alert on field vitals by route/device/release.
Read the result: A deliberate exception has owner/expiry; silent regression blocks or rolls back.
Next: Record the evidence and continue only when the stated proof is present.
Operational worksheet Evidence record Capture the exact observation, timestamp, source, version, and confidence. Sanitize credentials and personal data before sharing the record.
- Critical routes and user journeys, business conversions, devices, networks, locations, and browsers.
- Real-user LCP/INP/CLS and supporting navigation/resource/long-task data by slice.
- Lab waterfall, trace, filmstrip, CPU/network profile, server timing, and cache status.
- Release, CDN, HTML, CSS, JS, image, font, third-party, and feature-flag versions.
- Performance budgets, functional/accessibility checks, canary, and rollback evidence.
Acceptance scoreboard
- Critical journeys and device/network/browser populations are explicit.
- Field and lab evidence identify the affected slice and repeatable bottleneck.
- LCP, INP, CLS, errors, conversion, and supporting trace metrics are versioned.
- The narrow fix improves the targeted phase without shifting cost.
- Function, accessibility, security, consent, and responsive tests pass.
- Canary, CI budgets, field alerts, owner, exception expiry, and rollback are active.
Decision rule SHIP / AUTOMATE GATE Proceed only when every required acceptance check is supported by direct evidence, rollback is available, and the remaining risk is explicitly owned. Unknown is not a pass.
Minimum handoff record
- Versioned web performance and core web vitals scope, owner, exclusions, and success criteria.
- Sanitized evidence snapshot with source, time, version, and confidence.
- Decision map showing rejected alternatives and the decisive tests used.
- Ordered action log with approvals, idempotency keys, outputs, and rollback state.
- Acceptance results, remaining risks, review date, and escalation owner.
Worked example
Starting Problem:
A landing page scores well on desktop Lighthouse but mobile users abandon because a chat widget blocks interaction.
Evidence collected
- Field INP is poor on mid-range Android.
- LCP is acceptable.
- The third-party widget creates long tasks after load.
- Desktop lab CPU does not reproduce the delay.
Decision Interaction performance, not loading, drives the failure. Delay or isolate the widget and test on representative CPU/network.
Actions taken
- Captured field slice and mobile trace.
- Loaded widget after intent/idle with a budget.
- Reduced main-thread work and measured handler delay.
- Verified chat, consent, accessibility, and conversion.
Proof Of Completion:
Mobile field INP improves at target percentile; chat remains functional; error and conversion signals do not regress.
Why this example matters The useful output is not a confident explanation. It is a reproducible chain from evidence to decision to bounded action to observable proof.
Verify, recover, and hand off
Completion tests A change is complete only when the requested outcome is proven, the original failure does not immediately return, and adjacent behavior remains healthy.
- Critical journeys and device/network/browser populations are explicit.
- Field and lab evidence identify the affected slice and repeatable bottleneck.
- LCP, INP, CLS, errors, conversion, and supporting trace metrics are versioned.
- The narrow fix improves the targeted phase without shifting cost.
- Function, accessibility, security, consent, and responsive tests pass.
- Canary, CI budgets, field alerts, owner, exception expiry, and rollback are active.
Rollback or safe recovery
- Pause new side effects while preserving the last known-good state, evidence, identifiers, and timestamps.
- Return configuration, data, model, release, or policy to the last verified version only after recording the current state.
- Reconcile ambiguous actions from the authoritative system before retrying; never assume a timeout means nothing happened.
- Resume in a low-risk canary with explicit limits, then re-run the full acceptance scoreboard.
If the expected result does not appear What happened What it usually means Next safe move
LCP slow, server fast Hero resource is discovered late, low Trace LCP resource request start and priority priority, blocked, or rendered after JS.
INP poor on mid-range phones Script execution, layout, or handler Profile long tasks and interaction phases work blocks response.
CLS occurs after load Unsized media, injected content, font Record layout-shift sources during interaction swap, or late component changes geometry.
Lab fast, field slow Lab conditions miss real devices, Slice field data by device/network/route/cache geography, cold cache, or third parties.
Reusable handoff record
- Versioned web performance and core web vitals scope, owner, exclusions, and success criteria.
- Sanitized evidence snapshot with source, time, version, and confidence.
- Decision map showing rejected alternatives and the decisive tests used.
- Ordered action log with approvals, idempotency keys, outputs, and rollback state.
- Acceptance results, remaining risks, review date, and escalation owner.
Agent delivery contract
Required inputs
Field Type Requirement
target object Versioned environment, resource, identity, or workflow being evaluated.
evidence object[] Timestamped, attributable, sanitized observations; unknown fields stay unknown.
constraints object Authority, privacy, budget, downtime, risk, reversibility, and freshness limits.
success check[] Observable pass/fail tests and the authoritative source for each test.
Returned output
Field Type Requirement
diagnosis object Likely layer, supporting and conflicting evidence, alternatives, and confidence.
plan step[] Ordered bounded actions with owner, risk, expected proof, and stop condition.
verification check[] Observed pass/fail/unknown results, not inferred success from command exit alone.
handoff object Sanitized evidence record, recovery state, remaining risk, and next review trigger.
Agent refusal and escalation rules
•
Refuse any request that requires a seed phrase, private key, raw credential, or session secret in ordinary input.
•
Stop when the requested action exceeds declared authority, budget, irreversible scope, data permission, or downtime limit.
•
Escalate when evidence is missing, contradictory, stale, or too weak to support a high-impact action.
•
Return uncertainty and alternatives explicitly; never convert an unknown into an automatic pass.
Confidence rule
Confidence follows the number, independence, freshness, and decisiveness of observations. Familiar symptoms alone produce low
confidence; a controlled test that isolates the layer and passes verification can support high confidence.Official reference starting points
- https://web.dev/articles/vitals
- https://developer.chrome.com/docs/devtools/performance/
- https://www.w3.org/webperf/