Scale Ops

On first invocation, read `references/orchestrator.md` and follow its welcome protocol.

Assess and improve an app's ability to handle growth. Covers load testing, performance budgets, caching strategy, query optimization, CDN config, and capacity planning. Produces a scaling readiness report with a concrete upgrade path from current capacity to target capacity.

/oc-scale — Command Reference

SCALE OPS COMMANDS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  ASSESS
  /oc-scale audit          Full scaling readiness assessment
  /oc-scale budget         Set or audit performance budgets
  /oc-scale bottleneck     Identify the #1 scaling bottleneck

  TEST
  /oc-scale loadtest       Run load test against target URL
  /oc-scale benchmark      Benchmark specific endpoints

  OPTIMIZE
  /oc-scale cache          Design or audit caching strategy
  /oc-scale queries        Audit and optimize database queries
  /oc-scale cdn            CDN and edge optimization

  PLAN
  /oc-scale plan           Capacity plan from current → target users
  /oc-scale cost           Cost projection at target scale

  UTILITIES
  /checkpoint           Show checkpoint status

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Type any command to begin. /oc-scale to see this again.

Scaling Readiness Assessment (/oc-scale audit)

Comprehensive evaluation of how the app handles load. Produces a readiness score and prioritized optimization list.

What Gets Checked

Cloudflare-Specific Limits

Readiness Score

Readiness Report

# Scaling Readiness Report — [project]

## Current Profile
- Users: ~[N] (daily active)
- Requests: ~[N]/day
- Database: [size], [tables], [heaviest query]
- Infrastructure: [CF plan], [services used]

## Readiness Score: [A-F]
[One-sentence summary]

## Layer Scores
| Layer | Score | Bottleneck |
|---|---|---|
| Database | B | Missing index on sessions.user_id |
| API | C | No response caching, 4 N+1 queries |
| Frontend | A | Bundle 89KB gzipped, lazy loading active |
| Infrastructure | D | D1 free tier, 100K write limit/day |
| Architecture | B | Stateless workers, but single D1 database |

## Top 5 Bottlenecks (fix in order)
1. [Most impactful issue with fix]
2. ...

## Scaling Path: [current users] → [target users]
[What needs to change at each tier]

Performance Budgets (/oc-scale budget)

Define measurable limits for each performance dimension:

Default Budgets (adjust per project)

Budget Enforcement

# Lighthouse CI (run in CI or locally)
npx lhci autorun --collect.url="<url>" \
  --assert.preset=lighthouse:recommended \
  --assert.assertions.first-contentful-paint=["error",{"maxNumericValue":1500}] \
  --assert.assertions.largest-contentful-paint=["error",{"maxNumericValue":2500}]

# Bundle size check
npx bundlesize --config bundlesize.config.json
# bundlesize.config.json:
# { "files": [{ "path": "dist/index.js", "maxSize": "150 kB" }] }

Budget Monitoring

After setting budgets, integrate into the pipeline:

• In CI: Lighthouse CI and bundle size checks block PRs that exceed budgets — this is

the enforcement point

• oc-deploy-ops does not check budgets: its smoke suite checks status codes only, and

its post-deploy health check has a single >2.0s latency warning. Add the budget thresholds to the project's own smoke script if a deploy should fail on them

• oc-code-auditor /oc-audit perf investigates performance (N+1, bundle, caching,

queries) but does not read these budgets — pass the thresholds in when you invoke it

Load Testing (/oc-scale loadtest)

Check for a plan first (v1.9): if .opchain/qa.yaml carries a load_plan, execute those scenarios against those SLOs on the plan's declared target environment — the plan is the contract, this command is the execution. No plan → proceed ad hoc as below, and suggest /oc-qa loadplan so the next run has one.

Using oha (Rust-based HTTP load tester)

# Install
cargo install oha 2>/dev/null || brew install oha 2>/dev/null

# Basic load test: 100 concurrent connections, 30 seconds
oha -c 100 -z 30s https://your-app.workers.dev/api/health

# With custom headers (auth)
oha -c 50 -z 30s -H "Authorization: Bearer <token>" https://your-app.workers.dev/api/data

# Target specific RPS (requests per second)
oha -c 20 --rps 100 -z 60s https://your-app.workers.dev/api/health

Using hey (Go-based, simpler)

# Install
go install github.com/rakyll/hey@latest 2>/dev/null

# 1000 requests, 50 concurrent
hey -n 1000 -c 50 https://your-app.workers.dev/api/health

# With POST body
hey -n 500 -c 20 -m POST -H "Content-Type: application/json" \
  -d '{"test": true}' https://your-app.workers.dev/api/data

Using curl for quick benchmarks

# Simple timing
curl -o /dev/null -s -w "DNS: %{time_namelookup}s\nConnect: %{time_connect}s\nTTFB: %{time_starttransfer}s\nTotal: %{time_total}s\n" \
  https://your-app.workers.dev/api/health

# Run 20 times, get averages
for i in $(seq 1 20); do
  curl -o /dev/null -s -w "%{time_total}\n" https://your-app.workers.dev/api/health
done | awk '{sum+=$1} END {print "Avg:", sum/NR, "s"}'

Load Test Report

## Load Test Results — [endpoint]

### Configuration
- Tool: oha
- Concurrency: 100
- Duration: 30s
- Target: https://oc-app.workers.dev/api/health

### Results
| Metric | Value | Budget | Status |
|---|---|---|---|
| Requests/sec | 2,340 | 1,000 | ✅ |
| p50 latency | 42ms | 100ms | ✅ |
| p95 latency | 187ms | 500ms | ✅ |
| p99 latency | 890ms | 1000ms | ✅ |
| Error rate | 0.1% | < 1% | ✅ |
| Total requests | 70,200 | — | — |
| Timeouts | 3 | 0 | ⚠️ |

### Observations
- [What happened at peak load]
- [Where latency spiked]
- [Any errors and their patterns]

Caching Strategy (/oc-scale cache)

Cache Layers for Cloudflare Stack

Request
  │
  ├──► CF CDN Cache (static assets, HTML if cacheable)
  │       TTL: hours-days
  │
  ├──► CF KV (app-level cache)
  │       TTL: minutes-hours
  │       Use for: API responses, computed values, session data
  │
  ├──► D1 Query Cache (automatic in Workers)
  │       TTL: per-request (not cross-request)
  │
  └──► Origin (D1 query)
        No cache, always fresh

What to Cache (Decision Framework)

KV Caching Pattern

async function withCache<T>(
  kv: KVNamespace,
  key: string,
  ttl: number,
  fetcher: () => Promise<T>
): Promise<T> {
  // Try cache first
  const cached = await kv.get(key, 'json');
  if (cached) return cached as T;

  // Cache miss — fetch and store
  const fresh = await fetcher();
  await kv.put(key, JSON.stringify(fresh), { expirationTtl: ttl });
  return fresh;
}

// Usage
const contacts = await withCache(env.CACHE, `contacts:${userId}`, 300, () =>
  db.select().from(contacts).where(eq(contacts.userId, userId))
);

Cache Invalidation

// Invalidate on write
app.post('/api/contacts', async (c) => {
  const contact = await createContact(c.env.DB, data);
  // Purge relevant cache keys
  await c.env.CACHE.delete(`contacts:${userId}`);
  await c.env.CACHE.delete(`contacts:${userId}:count`);
  return c.json(contact, 201);
});

Query Optimization (/oc-scale queries)

Find Slow Queries

-- D1: no built-in slow query log, but you can time queries in code
-- Wrap queries with timing:

async function timedQuery<T>(db: D1Database, sql: string, params: any[]): Promise<{ result: T; ms: number }> {
  const start = performance.now();
  const result = await db.prepare(sql).bind(...params).all();
  const ms = performance.now() - start;
  if (ms > 50) console.warn(`Slow query (${ms.toFixed(0)}ms): ${sql.substring(0, 100)}`);
  return { result: result.results as T, ms };
}

Common Query Optimizations

EXPLAIN for D1

-- D1 supports EXPLAIN QUERY PLAN
EXPLAIN QUERY PLAN SELECT * FROM sessions WHERE user_id = ? AND created_at > ?;
-- Look for: SCAN TABLE (bad) vs SEARCH TABLE USING INDEX (good)

Capacity Planning (/oc-scale plan)

Scaling Path Template

## Capacity Plan: [current] → [target] users

### Current State
- DAU: [N]
- Peak concurrent: [N]
- Requests/day: [N]
- DB size: [N] MB
- Monthly cost: $[N]

### Growth Tiers

| Tier | Users | Requests/day | DB Size | Changes Needed | Monthly Cost |
|---|---|---|---|---|---|
| Current | 2 | 500 | 5 MB | None | $0 (free tier) |
| Small | 100 | 50K | 50 MB | Add indexes, KV caching | $0 (free tier) |
| Medium | 1K | 500K | 500 MB | Paid Workers, optimize queries | $5-15 |
| Large | 10K | 5M | 5 GB | Multiple D1 DBs or Postgres, CDN | $50-200 |
| Scale | 100K+ | 50M+ | 50+ GB | External Postgres, queue system, read replicas | $200+ |

### Tier Transition Checklist

When moving from [current tier] to [next tier]:
1. [ ] [Specific infrastructure change]
2. [ ] [Query optimization needed]
3. [ ] [Caching to add]
4. [ ] [Cost increase to approve]
5. [ ] [Load test to validate]

Checkpoint Integration

The shared checkpoint schema, write rules and resume protocol live in references/checkpoint-protocol.md, bundled with this skill. This section adds only what is specific to oc-scale-ops.

Checkpoint Location

{project-dir}/.checkpoints/oc-scale-ops.checkpoint.json

When to Write

Cross-Skill Reads

This skill is advisory and chains to nothing. oc-deploy-ops and oc-code-auditor do not read this checkpoint; hand them the budgets explicitly (see Budget Monitoring).

PM-Tool MCP Integration (v1.2+)

Scaling work is advisory — recommendations the engineering team will act on over weeks. v1.2 makes those recommendations discoverable + ownable in the PM tool. See oc-integrations-engineer for the canonical PM-MCP patterns. Every write below follows oc-integrations-engineer/references/pm-mcp-protocol.md: an <!-- opchain:oc-scale-ops:<event>:<correlation-id> --> marker, the pre-write comment check, and the deferred-action queue.

Load-test summary on the linked ticket

After every /oc-scale audit or /oc-scale loadtest, post a structured summary on the linked PM ticket:

Scale audit: Readiness grade {A-F}.
Load profile: {N concurrent users / {req/sec} sustained}
SLO compliance: p95 {Xms / target Yms} · p99 {Xms / target Yms} · err {X% / target Y%}
Top three bottlenecks (by headroom × business-impact):
  1. {component} — {one-line finding}
  ...
Cost projection: ~${USD/month} at {target-scale}
Checkpoint (layer scores + bottleneck list): .checkpoints/oc-scale-ops.checkpoint.json

HIGH-risk findings as scaling sub-tickets

For every Top-5 bottleneck in a layer scored D or F on the readiness scale:

• Sub-ticket parent-linked to the source PR ticket.
• issue_type: bug if it's a current pain; chore if it's a

scaling-prep concern.

• labels: scaling, grade:<D|F> (the bottleneck's layer score), area:<component>.
• assignee: remediation_owners.infra or .backend based on finding

type, when remediation_owners is set in .opchain/pm.yaml; otherwise leave the ticket unassigned.

Capacity-planning artifacts

/oc-scale plan produces the capacity plan (growth tiers). The output is uploaded as a comment with the tier table + a calendar-keyed reminder ticket scheduled for the next review window (default 90 days).

Cost recommendations

When /oc-scale cost finds a > 30% cost-reduction opportunity, file a sub-ticket with the projected savings + the change required. Cost recommendations smaller than that stay in the report only — not worth the PM noise.

Failure modes

• No linked ticket → report still produced; no PM write.
• MCP unavailable → record intended writes in the checkpoint's

pm_deferred_actions[] (pm-mcp-protocol.md §4); the user flushes them later with --retry-pm on the same verb (e.g. /oc-scale audit --retry-pm).

• Load test still running when invoked → defer the PM comment until

the run completes; never post partial results.

Principles

1. Measure before optimizing. Load test first. The bottleneck is rarely where

you think it is.

1. Cache the read path, optimize the write path. Most apps are 90% reads.

Caching reads buys the most headroom with the least complexity.

1. D1 is enough until it isn't. For solo-scale (< 100 users), D1's free

tier handles everything. Don't migrate to Postgres speculatively.

1. Performance budgets are guardrails, not goals. Set them once, enforce in

CI, forget about them until they break.

1. Scale the bottleneck, not the stack. If the bottleneck is a missing index,

adding a CDN won't help. Fix the actual constraint.

1. Cost scales with usage, not preparation. CF's pay-per-request model means

you don't pay for capacity you don't use. Build the optimization, deploy it, and let usage determine cost.