Docs menu
On this page

Contribute

Writing game scenarios

Last updated

Scale or Fail is the system design game in the practice page's Daily menu (Arcade) (play it). You pick a scenario, place components on a board by tapping or dragging, and keep the system up while traffic grows, new use cases arrive and the requirements tighten. Every number comes from Proschi's simulation, and every failure says why it happened and what a senior engineer would do.

This page explains how the game works and how to add to it: scenarios, tech cards, incidents and components are plain files in frontend/src/game/content/, checked by proschi game check.

How a run works #

A run is twelve waves in three acts. Once the twists are open (see First runs) it starts with a choice of three mutators (below), and each wave is a month of traffic:

  1. Forecast. Kernel, the cat SRE lead, briefs the wave in plain words: how traffic changed since last month, the new use cases and requirements, and the incidents coming (a boss wave opens with its own intro). The forecast panel then shows the traffic curve and its peak per use case, the requirements in force (as Proschi lines), and the incidents coming (with their tick, below difficulty 1), and this wave's three bounties to choose from. With the twists, the peak is a range: the real traffic lands within 12% of the forecast either way (20% on a boss), drawn from the seed, so a load test, which tests the middle, is a guide and headroom is a choice, and from wave 5 some incidents are unannounced. The cat button in the run's header turns the briefings off.

  2. Plan. Place, wire, scale out (replicas), scale up (sizes S, M, L), shard, remove. Nothing is timed. A load test shows the plan at the forecast peak for $100. The board is drawn on the editor's canvas (the same nodes and connections as a diagram), and Code shows it as Proschi text you can edit instead: one line per component (api "App Server" [Service] x3), one per wire, and size and shards in a capacity block. Which use cases an app server handles is set in its settings, or written after its line as # handles: book, pay (use case keys). Users and the externals stay on the board: their lines cannot be typed into. Compiled shows the whole document the simulation runs: the board with the scenario's use cases, the peak traffic and the requirements, and after a load test (or during the run) a warning on each line that broke. See The code pane.

  3. Run: hold the line. Eight ticks, each one simulated with the wave's traffic at that point of the curve, and the run keeps going while you act. With the twists, change the board as you would when planning and ship it: it goes live after provisioning, a tick for scaling or removing a component, two for new components or wires, and a cache that goes live mid-wave starts cold (30%, then 70% of its usual hit ratio). Three live changes a wave; one still provisioning when the wave ends is live for the next. And there are three hotfixes a wave (more with cards and perks), each from that tick to the end of the wave:

    Hotfix Cost What it does
    One more replica $200 On the node you tap.
    Bring it back $100 A node an incident took down (a lost zone, a dead primary) is back.
    Warm the cache $150 A cold cache (a stampede) is warm again.
    Rate limit 2 Trust Turns away 15% of requests and every bot at the edge.
    Switch a feature off 3 Trust A use case gets no traffic: no load, no revenue, no limits checked.

    A hotfix acts at once and costs overtime; a live change is free but takes time. Pause stops the clock for those who need it. (Hotfixes are not the On-call mode, whose pages are tickets.)

  4. Score and debrief. Revenue, cost, interest, bonuses and the bounty. If anything broke, the debrief shows the bottleneck, the simulation's hint and the review cards that explain it.

  5. Draft. Take one of three tech cards, or skip it for $100. Rerolls cost $150, then $50 more each. With the twists, after waves 2, 5 and 8, choose one of three contracts: a new use case for more revenue, stricter requirements for a multiplier, or cash now.

Waves 4, 8 and 12 are bosses: a launch, a holiday, a Super Bowl ad. After wave 12 you can bank the score or keep going in Endless (traffic ×1.3 a wave, two incidents, up to wave 24).

First runs #

So that a first run is not a dozen ideas at once, a new player plays the basic rules until their first clear of a Scale or Fail scenario (Shortly, for nearly everyone; clearing a design-first mode does not count):

  • no mutators and no bounties;
  • an exact forecast instead of a range, and no unannounced or cascading incidents;
  • no live changes: the board deployed is the board of the whole wave (hotfixes still work);
  • no card sets and no contracts.

In Shortly's first wave, after the briefing, Kernel walks through a short tutorial: place a load balancer, add a replica, load test, deploy. Each step is read off the board (undo steps back), its control pulses, and "Skip the tutorial" puts it away. The first run with the twists opens with Kernel's one-time intro to them, before the mutator picker. Both are remembered in the browser (proschi.onboarding, arcade and arcade-twists).

The gate is part of the run's setup (twists: false in RunSetup; absent means on), decided from the player's progress when the run starts (runTwists in engine/meta.ts), so a replay plays the same rules. The Worker starts a ranked run with it from the stored progress, never from the request, and takes an imported run's basic rules only while the progress at that point had no clear (twistsAllowed). The daily run always has every twist, for everyone, so its board compares one game. Basic runs score on the scenario's ordinary board: they can only be ascension 0, they lose the mutator, bounty and set bonuses, and they gain an exact forecast.

The code pane #

The game teaches Proschi as it goes. A scenario's code setting opens the code pane in steps:

  • Watch (before the wave in edit): the Code tab is read-only, and every change on the board lights up the line it wrote.
  • Edit (from edit): type the board, with completion that offers only what you can place (Ctrl+Space).
  • Only (from only): on a wide screen the palette is gone, and new components are typed; nodes are still tapped to scale, size or remove. On a phone the palette stays.

Kernel says when a step begins. The terminal button in a run's header turns Code only on for any scenario, as a player's own choice; it changes nothing in the score.

Mutators and bounties #

So that no two runs want the same design, a Scale or Fail run with the twists (not the design-first modes, nor first runs) has two kinds of twist, both seeded like everything else: the daily run offers everyone the same ones.

  • Mutators. Before the first deploy, pick one of three, or play it straight. A mutator changes the whole run: 60% of users on another continent, a SQL licence 75% dearer, reads ×1.5 and writes halved, writes ×3, a zone outage on waves 3, 6 and 10, 60% of the seed money with twice the interest cap, or a cache stampede on waves 5 to 7. Each multiplies every tick's points (×1.1 to ×1.3), the harder the more. Deploying without a pick plays it straight. The pick is an action like any other, so the Worker replays it.
  • Bounties. Every wave offers three optional objectives; take one before deploying, or none. Met, it pays; missed, it costs a quarter of its cash. The objectives: every app server under 50% at the peak, a cloud bill under 40% of revenue, a wave without a breach, the right-sized bonus, a clean wave without a hotfix or without a load test, a lost zone survived, a boss without a dropped request. Met, it pays its cash at once and its points × the act. A bounty made for the wave (its announced incident, its boss) is four times as likely, and the one taken last wave is not offered again.

Bounties and contracts are both optional offers, but different decisions, so they stay apart: a bounty is a goal for one wave that pays if met and costs a little if missed, and changes nothing else; a contract changes the rest of the run (a new use case that grows each wave, a stricter requirement, or cash for a tighter SLA) and has no goal to meet.

Cash, Trust and score #

  • Cash starts at the scenario's seed round. Each tick adds the revenue of the requests that succeeded and takes the cloud bill (the simulation's monthly cost, egress included, over the ticks). At the end of a wave you get 5% interest, at most $100. Below $0 at the end of a wave, the run is over (bankrupt).
  • Trust starts at 100. Each tick, a missed latency limit costs 3, a missed availability limit 5, a lost zone you could not survive 5, dropped requests 1 per 2% (at most 10), a use case with no route 8, a backlog older than its freshness limit 2, a seat sold twice 5. A clean wave gives 5 back, a boss 15. At 0, users churn and the run is over.
  • Score is the revenue of every tick × quality × the uptime streak. Quality is 1 for a clean tick, 0.6 with a latency, cost or freshness breach, 0.4 with anything worse. The streak grows by 0.1 per clean tick up to ×3, and any breach resets it. A wave where every compute and store node stays under 75% at the peak, none could lose a replica and stay there, and something works above 40% earns the right-sized bonus (+15%), and in Scale or Fail a tenth of the wave's bill back in cash. Bosses add 500 × the act, and a met bounty its points × the act. A mutator multiplies every tick's points. The end adds Trust × 10 and cash ÷ 10.

Cards with a price, and sets #

Some cards bend a rule and charge for it: Kubernetes autoscales but every app server costs 25% more, Read replicas everywhere takes 60% more reads at 35% more per database, Long TTLs raise every hit ratio but cost Trust. A card's downside is a second effect against you.

With the twists, three cards of one topic (caching, resilience, estimation…) make a set: every tick's points ×1.1 per set held.

Incidents that cascade #

With the twists, an incident with then sets off another when it broke something badly (dropped or failed requests, a lost zone it could not survive), at most once a wave: a lost cache node comes back cold (a stampede), a stampede knocks the database primary over, a dead primary brings a storm of retried writes. The next one starts the tick after, unannounced. Handle the first (or have the design for it) and there is no second.

Progression #

A run earns Blueprints: 1 per wave survived, 3 per boss, 1 per 2 500 points (at most 10), and 5 for a scenario's first clear. Blueprints buy:

  • Components. The first run has a load balancer, app servers and a SQL database. Caches, CDNs, queues and workers, firewalls, object storage, gateways, NoSQL, search and warehouses are unlocked one by one, each with a short intro to what it solves, what it costs and how it fails.
  • Features: instance sizes, sharding, wider lanes.
  • Rare cards for the draft (common and uncommon ones are in from the start).
  • Perks, permanent and equipped into up to three slots: more seed money, more Trust, a free reroll, a starting card, a free load test, a second pager.

Scenarios open as you reach waves in earlier ones, and each has ten difficulty levels (ascensions): you may play one above the highest you cleared. Unlocks and perks count on the leaderboard; each scenario and difficulty has its own board, and there is a daily run with the same seed for everyone. A finished daily run can be shared: a square per wave (🟩 no breach, 🟨 breached but survived, 🟥 lost), the score and the day's rank, with a link that opens today's daily run (#/arcade/daily).

Design-first modes #

Scale or Fail is the arcade mode. The others put the design first: no card draft, no rerolls, no boss names. Each wave a ticket lands in the inbox, from the product manager, the CTO, a customer, legal, finance or marketing, and asks for something real: a feature, a launch, an SLA, a law. The cash, Trust and score rules are the same, and so are the leaderboards.

The Arcade home lists them apart from the Scale or Fail scenarios, under Design challenges: one scenario per mode, each card with a line on what its mode asks.

Chaotic Startup (Pawprint) is about change. Besides scaling, it has:

  • API versions. A breaking change ships as a new use case (v2) next to the old one. Old clients keep calling v1, with traffic falling wave by wave. Once v2 is live, v1 costs its upkeep every wave until you sunset it, and sunsetting it while it still has traffic gives those clients 410 Gone (a compat breach, every tick).
  • Migrations. A schema change goes expand → dual-write → backfill → cutover → contract, one phase a wave (each is a deploy), and can be rolled back until the contract. Dual writes double the writers' writes on the store; the backfill adds a background job; the use cases that need the new shape are served from the cutover; and the contract drops the old shape, which breaks any use case still reading it (compat). All at once jumps to the end: the store's writes lock for two ticks (a migration breach).

On-call (Dinnerbell) is about incidents. Each wave's ticket is a page with its alert and logs, the incident really happens, and before deploying you name the root cause from a few plausible ones: right gives Trust back and points, wrong costs Trust, and every answer explains why. Then you fix it on the board, and the next page tests whether the fix holds.

Legacy rescue (Monolith) is about change without downtime: put a gateway in front of a ten-year-old monolith, move one use case at a time to new app servers (an app server's settings say which use cases it handles), split a table out with a migration, and retire the old endpoint once its clients are gone. A big-bang rewrite locks writes and breaks the old readers.

Cost crunch (Runway) is about spending less without breaking anything: finance lowers a cost <= … usd/month requirement every wave while the SLOs stay. Remove what is idle, right-size what is over-built, keep the cache that spares the database, and keep two of everything for the failure drills.

How the game uses the simulation #

The board is a graph of components and wires, but the simulation reads use cases: sequences of steps. The engine (frontend/src/game/engine/) compiles the board and the scenario's use cases to Proschi source, which the ordinary parser reads and the ordinary simulation analyses, once per tick:

  • A use case enters at Users, passes the edge components it is wired through (load balancer, firewall, CDN, gateway) on the shortest path, and reaches the first app server that handles it.
  • Each step runs from that app server: read db goes to the first database it is wired to, call push to the external system with that id.
  • With a cache wired to the app server and a cache hit ratio, reads go cache-aside: "Cache hit", "Cache miss" (which fills the cache) and "Cache down" (a fallback, so the cache does not count against availability, but a failed call costs its timeout).
  • With a CDN on the path and an edge hit ratio, an "Edge hit" scenario ends at the CDN.
  • Steps marked async go through a queue and a worker when the app server is wired to a queue whose worker reaches their targets. The request only publishes; the worker's work is a separate "(background)" use case, and a worker that cannot keep up builds a backlog (in minutes) instead of slowing the request. Without a queue, async steps run on the request.
  • Far users (a wave's global share) cross an ocean: 120 ms on the request, except for CDN edge hits, which are answered nearby.

Sizes, cards and incidents become capacity overrides; requirements are the scenario's Proschi lines, checked with runTests. "Open in editor" on the end-of-run report opens the compiled design. What the game adds on top of the simulation, and approximates:

Game rule How it works
Dropped requests A request is served with probability min(1, 1 / utilisation) at every node on its path.
Backlog Each tick adds 60 × (utilisation − 1) minutes of lag at the busiest background node, and drains the same way below 100%.
Availability zones Three zones; an outage takes a third of every component's replicas (rounded up). A single instance goes down with it.
Failover A SQL database's writes stop for the first tick while a replica is promoted; with shards, only one shard's share. Without a replica, it is down.
Hot key Caches and databases lose that share of their read capacity.
Bots Extra traffic on random keys; a firewall (403) or gateway (429) stops it at the edge.

The engine #

The engine is pure TypeScript with no React, shared by the page, the Worker (which replays every submitted run) and proschi game check. It is split by what each part decides:

File What it holds
engine/run.ts The core state machine every scenario shares: Game, waves, the deploy and load test, the card draft, scoring a wave and ending a run.
engine/state.ts The run's state and what it reports (RunState, TickResult, WaveSummary, Forecast), breach kinds and requirement helpers.
engine/tick.ts One tick of the simulation: traffic, capacity, analysis, what was served, breaches, backlog and points.
engine/incidents.ts Drawing the wave's incidents, what they do to a tick, and the on-call's hotfixes.
engine/twists.ts What a run adds after a first clear: mutators, the forecast range and unannounced incidents, bounties, contracts, cascades, card sets and live changes.
engine/modes/ One file per mode (scale, startup, incident, legacy, cost) and the mechanics they use.

A mode (modes/mode.ts) says whether waves end in a card draft, whether the twists apply, whether a right-sized wave gets cash back, and which mechanics its scenarios use. A mechanic owns its planning actions and hooks into the core: when a wave starts, before a deploy, how the wave's use cases are shaped and which are served, what locks a store's writes, which use cases get no answer this tick, the breaches after serving, and upkeep. There are three: migrations (Pawprint and Monolith: the migrate action, dual writes, backfills and big bangs), legacy-versions (the same two: sunset, upkeep and 410 Gone) and diagnosis (Dinnerbell: name the root cause). Runway needs none: its cost requirement is checked like any other. proschi game check refuses a scenario whose data needs a mechanic its mode does not play (a diagnosis in a cost scenario, say).

engine/determinism.test.ts replays every reference and wrong run (and the references with each mutator, under the basic rules, at higher ascension, with perks, into Endless, taking bounties, and with hotfixes and live changes) against a snapshot of every tick, forecast and refused action. A change that moves any score fails it; a deliberate rule change bumps GAME_VERSION and updates the snapshot with npx vitest run determinism -u.

The content folder #

frontend/src/game/content/
  components.json        placeable components and unlockable features
  perks.json             permanent perks
  ids.lock               every id ever published (never remove a line)
  cards/<id>.md          tech cards for the draft
  events/<id>.md         incidents and spikes
  scenarios/<id>/
    scenario.md          title, summary, prose: briefing, acts, debriefs, interview translation
    scenario.json        start board, use cases, waves, event pool, contracts
    reference.json       a scripted run that must clear all 12 waves
    wrong/<name>.json    scripted runs that must fail by a given wave

scenario.md #

Front matter (the same strict subset of YAML as problems and cards: flat keys, one-line lists, quote values with : in them):

Field
title, summary What the scenario picker shows.
difficulty easy, medium or hard.
tags Free words for the picker.
related Practice problem ids, linked from the end-of-run report.
cards Review card ids the report suggests.
order Position in the picker.
version Bump it when a change can change a score: it starts a new leaderboard season for the scenario.
mode scale (the default), startup, incident, legacy or cost. Every mode but scale has no card draft and gives every wave a ticket, and may have 4 to 12 waves.

Sections: ## Briefing (required), ## Act 1 to ## Act 3 (shown at the start of each act), ## Debrief: <id> (shown after a wave whose debrief names it), ## Ticket: <id> (the text of a wave's ticket), and ## Interview translation (required): the design in the words you would use in an interview.

scenario.json #

{
  "start": { "cash": 3000, "trust": 100, "board": { "nodes": [ … ], "edges": [ … ] } },
  "grants": ["storage"],
  "externals": [{ "id": "push", "name": "Push provider", "tech": "Push Service", "rps": 30000, "latencyMs": 60 }],
  "useCases": { "redirect": { … } },
  "waves": [ … twelve … ],
  "eventPool": [{ "id": "noisy-neighbor", "weight": 3 }],
  "contracts": [ … ],
  "unlock": { "scenario": "shortly", "wave": 6 },
  "code": { "edit": 3, "only": 9 }
}
  • start.board has a users node, every external, and only components unlocked from the first run or granted.
  • grants lends components for this scenario's runs whether the player unlocked them or not: the ones its lesson is about.
  • externals are systems you call but do not run: a catalog tech of the external kind, with optional rps and latencyMs.
  • unlock: reach this wave in that scenario to open this one. Leave it out for a scenario open from the start.
  • code: the waves (1-based) from which the code pane may be typed in (edit, 1 when absent) and from which new components are typed only (only, never when absent). See The code pane.

A use case:

"redirect": {
  "name": "Redirect",
  "method": "GET",
  "path": "/aZ3x9",
  "status": 302,
  "value": 250,
  "size": "500B",
  "steps": [{ "op": "read", "to": "db", "entity": "Url" }],
  "cache": 0.9,
  "edge": 0.85
}
Field
name The Proschi use case name; requirement lines refer to it. No quotes or brackets.
method, path, status The entry request and its answer.
value Revenue per wave for every 1 000 rps that succeed.
size Payload between the user and your edge: the upload for a POST, the response for a GET. It fills bandwidth, and responses to users are billed as egress (less from a CDN).
steps In order: {"op": "read" | "write", "to": "db" | "blob" | "search" | "warehouse"} or {"op": "call", "to": "<external id>"}, with optional entity, async (may run in a worker), x (fan-out) and size.
cache, edge Hit ratios (0 to 0.99) when a cache or CDN is in place; leave out for data that cannot be cached.
strong Reads must see the latest write: no cache, and an eventually consistent store is a breach.
optional Contracts and extras: a missing route costs less Trust.

A wave:

Field
traffic Base rps per use case key. Once a use case appears, every later wave gives its rps.
curve flat, day, ramp, spike (×4 for two ticks) or double-peak.
requirements Proschi requirement lines, each naming a use case: p99 "Redirect" < 50ms, availability "Checkout" >= 99.9%, durable "Shorten", survive any node failure, cost <= 4000 usd/month. A line for the same measure and use case replaces the earlier one.
freshness [{"useCase": "send", "maxMinutes": 5}]: how far background work may lag.
events Event ids that happen this wave, telegraphed.
contract Offer three contracts after this wave.
global Share of far users from this wave on.
boss, name Waves 4, 8 and 12 are bosses.
brief What Kernel says first when the wave begins, at most 240 characters: a boss's intro. The rest of the briefing comes from the wave itself.
debrief A ## Debrief: <id> section shown after the wave.

From wave 3, one incident a wave is also drawn from the eventPool (weighted, never the one drawn the wave before, and no spikes on a boss). A contract has an id, name and text, and any of: useCase with rps and growth (it adds that use case), requirements, freshness, cash, revenue (a multiplier on every use case).

Cards #

---
name: Connection pooling
icon: cable
rarity: common
topic: databases
learn: [connection-pooler, connection-pool-size]
effect: capacity
target: db
stat: rps
value: 1.2
---

## Text

Databases take 20% more reads and writes.

## Why

Every database connection costs the server memory…

icon is required: a kebab-case lucide name listed in frontend/src/game/engine/icons.ts (see Icons), and no other card may use it; its tile takes the card's rarity colour. rarity is common, uncommon, rare or legendary; unlock (Blueprints) makes a card buyable instead of in the pool from the start. learn lists review card ids. The effect is one the engine implements:

Effect target / value
capacity Component id or role, stat rps, reads or writes; multiplier.
latency, cost Component id or role; multiplier.
cache-hit, edge-hit Added to every hit ratio.
timeout What a failed call costs, in ms.
coalesce Cold caches and stampedes do nothing.
autoscale App servers and workers resize every tick.
write-batching Share of background messages that write.
payload Multiplier on every payload.
presigned Uploads go straight to object storage.
hot-key Multiplier on the hot-key penalty.
failover No write outage while a SQL replica is promoted.
reserved, spot Cost multiplier on app servers (no scaling below today's for 3 waves) or workers (they lose a replica in any incident).
trust, cash, interest, oncall, loadtest, streak Paid once, or a per-wave allowance.

A card may have a downside: downside (one of capacity, latency, cost, cache-hit, edge-hit, trust, interest) with downside-target, downside-stat and downside-value, which must work against the player (a multiplier above 1 on cost or latency, a negative Trust). Say it in ## Text.

Events #

---
title: Cache stampede
icon: snowflake
category: incident
topic: caching
learn: [cache-stampede, cold-cache-restart]
effect: cache-cold
target: cache
values: ["0", "0.5"]
duration: 2
telegraph: The cache cluster restarts for a version upgrade.
counters: [request-coalescing]
requires: [cache]
min-wave: 4
---

## What happened
## Why
## What a senior engineer would do

Effects: traffic (multiplier), write-surge (multiplier on the use cases that write, or target: async for those with background work), bots (multiplier of real traffic), az-down, node-down (the first component matching target), failover (a SQL database), cache-cold (values per tick, a share of the usual hit ratio), latency (multiplier), hot-key (share), external-slow (latency in ms; target an external id or none for all). from fixes the first tick; otherwise the seed picks it. then names the event it sets off when it caused a breach (see above). requires lists roles the board must have for the pool to draw the event. icon is required, as for cards, and unique among the events; its tile is red for an incident and pink for a spike. All three sections are required: they are the debrief.

perks.json #

{ "id": "seed-round", "icon": "piggy-bank", "name": "Bigger seed round", "text": "Start every run with $250 more per level.", "costs": [6, 10, 14], "effect": "cash", "value": 250 }

costs are the Blueprints for each level, value is the effect per level, and effect is one of cash, trust, free-reroll, starter-card, loadtest or oncall. icon is required and unique among the perks.

mutators.json #

{ "id": "licence-audit", "name": "Licence audit", "icon": "receipt", "text": "…", "why": "…", "score": 1.15, "cost": [{ "target": "sql", "mult": 1.75 }], "excludes": ["snapshots"], "learn": ["cache-aside"] }

score multiplies every tick's points (above 1, at most 2). The effects, any of them: cost (bill multipliers by component id or role), traffic (read for GET use cases, write for the rest), global (the far users' share from the first wave), cash and interest (multipliers on the starting cash and the interest cap) and events (an event id on given waves, 2 to 12). excludes lists the scenarios it would make impossible, so they never offer it. text says what changes, why the design it pushes toward.

bounties.json #

{ "id": "cool-servers", "name": "Cool heads", "icon": "gauge", "text": "Keep every app server under 50% busy at the peak.", "kind": "max-utilization", "role": "app", "value": 0.5, "cash": 150, "points": 250 }

kind is the test: max-utilization (every node of role under value at the peak), budget (the bill under value × revenue), clean, no-breach (no breach of kind breach all wave), right-sized, no-oncall and no-loadtest (a clean wave without a hotfix, or without a load test). event (an event effect) and boss limit it to waves that have that incident, or a boss. cash is paid at once, points × the act.

Icons #

Perks, mutators, bounties, cards and events each have an icon of their own: an icon may appear once in each of those, but not twice in one of them. The names are lucide's, listed in frontend/src/game/engine/icons.ts (no React, so proschi game check can read it) and mapped to their components in frontend/src/game/ui/gameIcons.tsx. To use a new icon, add its name to both; the frontend tests fail if the two lists differ.

Tickets, versions and migrations #

A wave's ticket: "ticket": {"id": "multi-pet", "from": "pm", "kind": "schema", "title": "Multi-pet bookings"}. from is pm, cto, customer, legal, finance, sre or marketing; kind picks its icon (feature, scale, compliance, mobile, region, api-version, schema, data-move, deprecation, security, cost, incident, reliability, analytics, performance). Its text is the ## Ticket: <id> section.

An old API version is a use case with "legacy": {"upkeep": 400, "replacedBy": "book-v2"}.

A migration, in "migrations":

{
  "id": "pets",
  "name": "the multi-pet migration",
  "entity": "Booking",
  "store": "db",
  "needs": ["book-v2"],
  "writers": ["book", "book-v2"],
  "oldReaders": ["book"],
  "backfillRps": 900
}

needs are served only from the cutover, writers write twice from the dual write to the contract, and oldReaders break once the old shape is dropped.

An on-call wave's diagnosis: a question and options, each with an id, text and why, exactly one of them "correct": true. A play picks one with "diagnose": "<id>" (the first option when it says nothing).

Reference and wrong runs #

Every scenario ships with scripted runs, like a problem's reference solution and wrong designs. A run is a seed, an optional loadout and ascension (and "twists": false for the basic rules of a first run), and a play per wave:

{
  "seed": "reference",
  "loadout": { "unlocked": ["cache", "cdn", "tiers"], "perks": {} },
  "plays": [
    {},
    {
      "add": [{ "id": "lb", "component": "lb", "replicas": 2 }],
      "set": { "api": { "replicas": 3 } },
      "unwire": [["users", "api"]],
      "wire": [["users", "lb"], ["lb", "api"]],
      "pick": ["async-io", "right-sizing"],
      "contract": "angel"
    }
  ],
  "expect": { "cleared": true }
}

A play changes the board deployed last wave (add, remove, set, wire, unwire), may loadtest, take a bounty (an id, or first), ship live changes during the run ([{"tick": 2, "set": {"api": {"replicas": 6}}}], each with the same add, remove, set, wire and unwire as a play), call the oncall for a hotfix ([{"tick": 3, "node": "api"}], or with "act": reboot, warm, ratelimit or shed with a useCase), reroll, pick the first card on offer from a list, sign a contract, migrate ([{"id": "pets", "to": "next"}]; to is next, rollback or big-bang) and sunset legacy use cases (["book"]). Waves past the list keep the board and skip every choice.

  • reference.json must clear all twelve waves ("expect": {"cleared": true}).
  • Each wrong/<name>.json is a plausible design that must lose by a wave ("expect": {"failsBy": 8}): no cache, no CDN, a provider called inline. It may also name the breaches it must show ("shows": ["compat"]), or only those, for a mistake the run survives. Add a note saying what it shows.
  • The check also plays "do nothing" (the start board, every wave), which must lose by wave 8 (or the wave before the last, in a shorter scenario).
  • And it plays the reference under the basic rules of a first run (no bounty or contract, and its live changes made before the deploy): it must clear Shortly, the scenario new players learn on, and get past act 1 in the other Scale or Fail scenarios.

Balancing #

cd tooling
npm run build
node dist/cli.cjs game sim shortly                 # the reference run, wave by wave
node dist/cli.cjs game sim shortly --seed other    # the same plays with other incidents
node dist/cli.cjs game sim shortly --run my.json --ascension 5
node dist/cli.cjs game sim shortly --basic          # the basic rules of a first run

sim prints each wave's cost, revenue, points, Trust and what broke. Good scenarios:

  • teach one new idea per wave, and make each act's last wave a boss;
  • break last wave's design every two or three waves (traffic about ×1.5 a wave), so there is always something to do;
  • burn cash early and turn a profit once the design is right (a hockey stick), with no single build that wins every scenario;
  • keep requirements achievable: a dependency at 99.9% caps the use cases that call it, and far users cannot have a 50 ms p99 without a CDN hit.

Checks #

node tooling/dist/cli.cjs game check     # everything below; exits 1 on any violation
node tooling/dist/cli.cjs game lock      # adds new ids to ids.lock

game check reads every file and checks: fields and their values, ids in ids.lock (and none removed), review cards, topics and practice problems that exist, card and event targets, icons (known, and unique within their kind), requirement lines that parse and name a use case, traffic for every active use case, start boards the first run allows, and the scripted runs. For every mutator a Scale or Fail scenario offers, it also plays the reference with that mutator through act 1, which it must survive: a twist may force a new design later, but should not end a sound one at once. And it flags a far-user mutator in a scenario with a latency limit the ocean alone breaks (a use case no edge can answer, under 120 ms): exclude it there. It plays the reference under the basic rules of a first run too (see Reference and wrong runs). The frontend tests run the same check.

Checklist #

  1. Write scenario.md and scenario.json (copy a scenario close to yours).
  2. Write reference.json and at least one wrong/*.json; tune with game sim until the reference clears with some margin and the wrong runs lose for the reason in their note.
  3. New cards or events: one file each, with learn cards and all sections. New mutators or bounties: an entry in mutators.json or bounties.json.
  4. node tooling/dist/cli.cjs game lock, then game check.
  5. npm test in frontend/ and tooling/.
  6. Open the pull request with a conventional commit title (feat(game): …); release-please adds it to CHANGELOG.md.

Edit this page on GitHub