performance-budget

name: performance-budget description: "Measure Lighthouse performance scores, bundle size delta, and/or k6 load-test throughput at Stage 6e. Compares against project budgets (performance.budget.json or .devteam/config.yml defaults). Produces pipeline/performance-report.md and writes the stage-06e gate. Gate FAILs when any budget is exceeded. Skip with skipped_reason for changes with no performance-relevant surface."

Performance budget

Use this skill at Stage 6e (after QA, on full / quick / hotfix tracks). Measures the three performance dimensions relevant to the change — Lighthouse Web Vitals, bundle size delta, and load-test throughput — and compares each against configured budgets.

When to use each check

When to skip entirely: If the change is purely backend with no HTTP surface change, doc-only, or infra config with no throughput impact, set skipped_reason and status PASS.

Budget thresholds

Look for budgets in this order:

1. performance.budget.json at the project root (preferred — machine-readable, shareable)
2. .devteam/config.yml under performance.budgets.*
3. These defaults when no config exists:

If performance.budget.json is absent, record that in the report and note which defaults were applied.

Procedure

1. Scope the change

Read pipeline/brief.md, pipeline/design-spec.md, and pipeline/test-report.md. Identify:

• Which pages or routes were touched (for Lighthouse)
• Whether new assets / imports were added (for bundle)
• Which endpoints were modified (for load test)

Based on the scope, decide which of the three checks to run. Record what you chose (and why you skipped any check) in the report.

2. Read the budgets

# Check for project budget file
cat performance.budget.json 2>/dev/null || echo "No performance.budget.json found"

# Check config
cat .devteam/config.yml | grep -A 20 "performance:" || echo "No config section"

3. Lighthouse audit (if frontend changes)

Start the app locally or point at a staging URL from the brief.

Using Lighthouse CLI:

npx lighthouse <URL> \
  --output json \
  --output-path pipeline/lhci-result.json \
  --only-categories performance \
  --chrome-flags="--headless --no-sandbox"

# Extract the score
node -e "const r = require('./pipeline/lhci-result.json'); \
  console.log('score:', r.categories.performance.score); \
  console.log('LCP:', r.audits['largest-contentful-paint'].numericValue); \
  console.log('INP:', r.audits['interaction-to-next-paint']?.numericValue ?? 'N/A'); \
  console.log('CLS:', r.audits['cumulative-layout-shift'].numericValue); \
  console.log('FCP:', r.audits['first-contentful-paint'].numericValue); \
  console.log('TTFB:', r.audits['server-response-time'].numericValue)"

Using Lighthouse CI (@lhci/cli):

npx lhci autorun --config=lighthouserc.js

Using npm run lighthouse (check package.json scripts first — many projects already configure this):

cat package.json | jq '.scripts | to_entries[] | select(.key | contains("lighthouse", "perf", "lhci"))'

Record: score, lcp_ms, inp_ms, cls, fcp_ms, ttfb_ms, url, tool.

Compare against budget. Any metric exceeding budget → budget_exceeded: true → stage FAIL.

4. Bundle size (if bundled JS/CSS changed)

Using bundlesize (if configured in package.json):

npx bundlesize

Using size-limit:

npx size-limit

Manual delta calculation (always works, no extra tool):

# Build and measure
npm run build 2>/dev/null || yarn build 2>/dev/null

# Total size of all JS bundles
find dist/ build/ .next/static/chunks/ -name "*.js" -not -name "*.map" \
  -exec du -k {} + 2>/dev/null | awk '{sum += $1} END {print sum "KB total"}'

# Or use du on the entire output dir
du -sh dist/ build/ .next/ out/ 2>/dev/null | head -5

Delta vs baseline: If git diff shows the bundle changed:

# Get baseline size from main/master
git stash && npm run build && du -sk dist/ > /tmp/baseline_size.txt && git stash pop
npm run build && du -sk dist/ > /tmp/current_size.txt
echo "baseline: $(cat /tmp/baseline_size.txt)  current: $(cat /tmp/current_size.txt)"

Record: total_size_kb, delta_kb, budget_kb, delta_budget_kb, budget_exceeded.

5. Load test (if API / endpoint changed)

Using k6:

# Run the project's existing k6 script, or create a minimal one
cat k6/*.js k6.config.js 2>/dev/null | head -50  # check for existing scripts

# If no script exists, create a minimal one:
cat > /tmp/k6_perf.js <<'EOF'
import http from 'k6/http';
import { check, sleep } from 'k6';
export const options = {
  vus: 10,
  duration: '30s',
  thresholds: {
    http_req_duration: ['p(95)<200'],
    http_req_failed: ['rate<0.01'],
  },
};
export default function () {
  const r = http.get('http://localhost:3000/api/health');
  check(r, { 'status 200': (r) => r.status === 200 });
  sleep(0.1);
}
EOF
k6 run /tmp/k6_perf.js --out json=/tmp/k6_result.json

Using autocannon (Node-native):

npx autocannon -c 10 -d 30 --json http://localhost:3000/api/health > /tmp/ac_result.json
node -e "const r = require('/tmp/ac_result.json'); \
  console.log('p95:', r.latency.p97_5 + 'ms'); \
  console.log('rps:', r.requests.average)"

Record: tool, scenario, p95_ms, p99_ms, rps, error_rate, budget_p95_ms, budget_rps, budget_error_rate, budget_exceeded.

6. Compute gate status

budget_exceeded = (lighthouse.score < budget_score)
               OR (lighthouse.lcp_ms > budget_lcp_ms)
               OR (bundle.budget_exceeded)
               OR (load_test.budget_exceeded)

• budget_exceeded: true → status: "FAIL" — list the failing metrics in blockers[]
• All budgets met, but some metrics are within 10% of limit → status: "WARN", note in warnings[]
• All budgets met → status: "PASS"

7. Write the report and gate

Write pipeline/performance-report.md using the template at templates/performance-report-template.md. Then write pipeline/gates/stage-06e.json.

Gate shape:

{
  "stage": "stage-06e",
  "status": "PASS",
  "orchestrator": "<from descriptor>",
  "track": "<from descriptor>",
  "timestamp": "<ISO-8601>",
  "blockers": [],
  "warnings": [],
  "checks_performed": ["lighthouse", "bundle"],
  "lighthouse": {
    "score": 0.91,
    "lcp_ms": 1850,
    "inp_ms": 95,
    "cls": 0.04,
    "fcp_ms": 720,
    "ttfb_ms": 180,
    "budget_score": 0.80,
    "url": "http://localhost:3000/dashboard",
    "tool": "lighthouse-cli"
  },
  "bundle": {
    "total_size_kb": 312,
    "delta_kb": 8,
    "budget_kb": null,
    "delta_budget_kb": 50,
    "budget_exceeded": false,
    "tool": "du"
  },
  "load_test": null,
  "budget_exceeded": false,
  "skipped_reason": null
}

When skipping entirely:

{
  "status": "PASS",
  "checks_performed": [],
  "lighthouse": null,
  "bundle": null,
  "load_test": null,
  "budget_exceeded": false,
  "skipped_reason": "Backend-only change (new /internal/metrics endpoint). No customer-facing page was modified. No bundle change. Load envelope is unchanged."
}

Common failure modes and fixes

Notes

• Run tests in a clean environment: Local dev mode is not representative. Use a production build (NODE_ENV=production) on a machine not under other load.
• Lighthouse needs a running server: Start the app first. Many projects have a preview or serve npm script.
• Load test against staging if local isn't possible: Record the base URL used so results are reproducible.
• No tool installed? Record attempted_but_blocked:<check> in checks_performed and add a warning explaining the install path. Don't fabricate numbers.