Setting the file. One moment.
Subchapter 7.16
references/scoring.mdMarkdown12 KBView on GitHub
This reference covers everything that happens after recommendations are drafted: quality floor, impact framing, sort order, the customer-facing report template, and the playbook selection matrix.
| Rule | Value | Why |
|---|---|---|
Drop recommendations with quality.overall < 0.55 | Hard cutoff (raised from 0.4 in May 2026 audit) | Bad-grade recs erode trust faster than they help. 0.55 matches the Poor/Fair grade boundary; recs below this are “Poor” and shouldn’t ship. |
| Prune cap on findings | 30% of input | Stops the pruner from wiping the report when LLM merit-grades are noisy |
| Platform-rec cap | 3 | Account-level recs (Fluid, Bot Protection, Speed Insights) only have room for the top three |
| Quick-wins definition | effort === 'low' AND priority > 40 | Surfaces fixes the user can ship in a single PR |
| Savings floor (internal ranking only) | $5/mo equivalent | Below this, even a “high” tier impact translates to “negligible” magnitude |
Performance: be precise. Use observed numbers. Example:
“Reduce /api/products p95 from 850ms toward ~250-400ms; cache hit would lift from 0% toward ~60% based on similar cached routes.”
Performance numbers come from signals.json.metrics.* — they’re observed, not extrapolated. Cite the exact route + metric value.
Dollar cost: never precise. Use MAGNITUDE BUCKETS via lib/impact-magnitude.mjs‘s impactMagnitude({currentCost, impactTier}):
| Estimated reduction (USD) | Magnitude | Customer-facing phrase |
|---|---|---|
| < $5 | negligible | “small cost impact at current traffic” |
| $5 – $50 | small | “low-tens of dollars per month at current traffic” |
| $50 – $500 | medium | “hundreds of dollars per month at current traffic” |
| $500 – $5,000 | large | “low-thousands of dollars per month at current traffic” |
| > $5,000 | very-large | “thousands+ of dollars per month at current traffic” |
Reduction is computed as currentCost × fraction where fraction = {high: 0.4, medium: 0.2, low: 0.1}[impactTier]. The fraction is intentionally conservative — we’d rather under-promise than mislead.
When the project is on a Flex Commit and the report frames savings against contract burndown, segment spend before phrasing. Field doctrine (May 2026): the Flex discount slider applies only to a subset of SKUs.
| Discountable (slider applies) | Non-discountable (raw rate) |
|---|---|
| Seats | Build CPU Minutes |
| Edge Requests | Fluid Active CPU |
| Fast Data Transfer | Fluid Provisioned Memory |
| Fast Origin Transfer | Raw Flex top-up |
| Image Optimization | |
| ISR Reads / Writes | |
| Observability Events |
A recommendation that targets a non-discountable SKU should never frame savings as a percentage of contract; frame as absolute magnitude only. Conversely, a discountable-SKU recommendation may surface “applies to contract burndown” in the magnitude phrase.
Why magnitudes:
$340/mo with a hand-wave behind it.$-strip sanitizer enforces this at output time. Any $N literal that slips into customer-facing fields is replaced with “the billed cost” before rendering.type ImpactLabel = {
// PRECISE: performance recs
performance?: string;
// MAGNITUDE: cost recs
costMagnitude?: 'negligible' | 'small' | 'medium' | 'large' | 'very-large';
costPhrase?: string;
billingDimension?: string; // 'Edge Requests' | 'Function Duration' | ...
fractionReduced?: number; // 0.2 = ~20% — internal only, NOT rendered
};Cost recs render costPhrase. Performance recs render performance. Reliability recs frame impact as observed error/timeout reduction (e.g., “Cuts 5xx rate from 0.4% to <0.1% based on current traffic”).
When a rec spans buckets — e.g., a caching fix that reduces both cost AND latency — render both lines.
Internal sort key (never rendered): priority = currentDimensionCost × fractionReduced × confidence.
The list of recs the customer sees is sorted by this priority. The platform recommendations section is capped at 3, sorted the same way.
The agent renders this as the final output of Step 4. The shape is fixed; the content comes from the merged signals + verified recommendations + the gated[] list from Step 2.
# Vercel Optimization Report — {projectName}
**Stack**: {framework}@{frameworkVersion} | {router} | {orm}
**Plan**: {plan.plan} ({plan.reason})
**Period**: {usage.period.from} → {usage.period.to}
**Observability**: {observability status}
## Cost breakdown
| Service | Usage | Billed Cost |
|---|---|---|
| (non-zero rows from usage.services, sorted by billedCost desc) |
Total billed: {usage.totals.billedCost} (we render the precise current cost — we just don't project future precise savings)
Omit zero-cost service rows from the table at the same cent precision shown to customers. If every row has `$0.00` billed cost but `effectiveCost` / USD `pricingQuantity` is non-zero, explain that net billed cost is `$0.00` after included credits or allotments and show the effective usage cost table instead. If both billed and effective costs are
Common data gaps to call out when the underlying metric returned empty rows. If the metric query failed (ok=false), say the metric was not usable with the code; do not convert failed queries into “no measurements” or “not used” claims.
cwv_poor gate stayed dormant; no claims about LCP/INP/CLS are made.isr_overrevalidation gate stayed dormant.middleware.ts (or matcher excludes all observed traffic). The middleware_heavy gate stayed dormant.next/image usage or no images served in the window.platform_bot_protection recommendation for the toggle.cold_start gate evaluates the data but emits no candidate.The “Not investigated in this run” section is critical. It comes directly from gate.json produced by the gate. It tells the user we considered everything; we didn’t just pick the easy targets.
The recommender selects 0-2 playbooks based on the project’s stack.applicationProfile (inferred from frameworks + deps) and the top billing dimensions.
| Application profile | Likely top dimensions | Apply playbooks |
|---|---|---|
ai-application (AI SDK, AI Gateway, Sandbox usage) | AI Gateway, Sandbox Active Compute, Function Duration | playbooks/ai-application.md |
ecommerce (Stripe, Shopify, cart components) | Edge Requests, Function Duration | playbooks/ecommerce.md |
saas (auth, dashboards, multi-tenant) | Function Duration, Bandwidth | playbooks/saas.md |
api-service (mostly API routes, no UI) | Function Duration, Edge Requests | playbooks/api-service.md |
content-site (blog, docs, mostly static) | Edge Requests, Image Optimization | playbooks/content-site.md |
marketing (landing pages, A/B tests) | Edge Requests, ISR Reads | playbooks/marketing.md |
ai-application is checked first in inferPlaybook() — an AI-heavy SaaS or AI commerce app shares the AI playbook’s billing shape (AI Gateway dominant) and gotchas, not the dashboard or cart-checkout patterns.
Playbooks shape phrasing and ordering of recommendations. They never invent claims — every rec must still trace back to verified findings.