name: new-design-problem description: Use when asked to build another system design problem in the guide (page, interviewer, API flows, simulations, narration, heavy test, pricing, how big companies do it) to the URL shortener's quality in hours, not days.

A new design problem, to the URL shortener's quality, in hours

Bruno, 2026-10-04 19:04 UTC, after two weeks on the URL shortener: "Am I delusional to think that we can copy/paste the features and menttality and quality from jev, to api spec to design positbiilityiess to simulations to any other question? Or will it take just as long as it did for this url problem?" and "i dont wanna spend days on a single problem perfecting it... i dont mind hours. but not days."

The honest answer, from reading the code at board 3.10 (origin/main 000ed34). Most of what the URL problem took (157 commits from 26 Sep to 4 Oct) built the board itself, and a second problem gets that for free: the drawing board, the flow editor, the pop-up, the voice player, the interviewer server, most of the heavy test's physics per kind of part. The content of a problem is hours of work. But the runner's world, the API's step vocabulary and the heavy test's request model are written for links, redirects, takedowns and clicks, in code that no content file can change. Make them general once (generalize.md), and each problem after that is hours. Skip that, and the next problem is days again.

Everything here was written while two helpers were changing the board (~/scratch/j2s-runner: what the simulations accept and the kinds of part; ~/scratch/j2s-words: every sentence and Katie's lines). Re-check names and line numbers after they merge.

The reference files, beside this one

1. What a finished problem is

Details, and his words for each: reference/finished-problem.md.

2. The order of work

1. Once, before any second problem: make the machinery general (reference/generalize.md, four steps, contract first, each proved by the URL problem's results staying identical).
2. Hour 0, one session alone: write the problem sheet, with the proven answer first (each requirement's usual pattern, where its data ends up, what an interviewer expects, with sources). Then the tests, the request mix and the levels. Ask Bruno one line where a reader-facing choice can be read two ways; show a picture before building anything new. Write the contract, commit it as the base, write the briefs.
3. Hours 1 to 3, up to four helpers in parallel, each in its own worktree and port block: the page and "how big companies do it"; the interviewer; the tests and the runner; the heavy test. The voice comes after the runner merges.
4. Merge, then a stranger's walk (a fresh session with only a browser), then one fix round.
5. Release the page, interviewer, API and simulations first; the heavy test and the big-companies section together next; the narration whenever its clips pass.

Measured rounds took about one and a half to two and a half hours each when no helper died. Plan, ports, the box's limits and a brief template: reference/plan.md.

3. The bars he set (quoted, with dates, in reference/quality-bars.md)

• It feels like an architecture interview: requirements, then the API, then the design, then scale (27 Sep, 4 Oct).
• No single answer, but the known patterns named, and always a way to improve (27 Sep, 4 Oct).
• Taught while doing; never uncovered by failing (4 Oct).
• A story with people, not a checklist; no status codes; unlocked easiest first (27 Sep).
• Human words, "Like if you were explaining it to your dad." (4 Oct).
• The eyes are on the diagram: the spot, the fix, why, re-simulated (27 Sep).
• A load that builds; real behaviour at interview depth; plain concept names (27-28 Sep, 4 Oct).
• Cost per part, as pictures, not prose (27 Sep, 4 Oct).
• Proven architecture, with diagrams and animation (4 Oct).
• Less text before the exercise (29 Sep). Slow enough to follow, and a voice that fits (27 Sep, 30 Sep, 4 Oct).
• No key needed; an interviewer that does not miss simple questions; UI checked and completed well (27 Sep).
• Ours, from costs: a check never seen red proves nothing; every picture opened; his Mac's widths; numbers from code or a dated source; code decides verdicts; the writer never sees the tests.

4. Research (reference/research.md)

• Capacity numbers carry a kind code (H, S, D, B, R) and a numbered source; estimates are listed apart and say so.
• Run a scratch model of a few designs at each level before building; its table becomes the unit tests.
• Prices from AWS's Price List files, proved against AWS's own worked examples, with the date read.
• Companies from their own engineering posts; a third party labelled; a conflict shown, not resolved.
• Traps: pages that hide prices until a region is picked; sources that block bots (read the Wayback copy); a fetch tool that summarises; paywalled pages; secondary figures inside primary-looking articles; doc pages that moved.

5. Make the machinery general (reference/generalize.md)

What a second problem cannot change from content today:

• the runner's world (resources-sim.js, and about 470 of flow-run.js's 805 lines): what a request is by its method, one key per request, the scenario's events, the checks, clicks, takedowns, the people and every sentence;
• the step vocabulary (flow.js CHECKS, marksBlocked, the click helpers; flow-view.js menus and modes; the writer's prompt; Say it's labels and GLOSSES);
• the voice's line ids, rebuilt from the runner's English sentences by regular expressions;
• the heavy test's request model (heavy.js PROBLEMS returns redirects, the hot link and creates; the Walk's columns are those requests plus one click each; the SLOs count redirects only);
• problem words in shared code, and browser checks wired to the URL page.

6. Mistakes not to repeat (reference/mistakes.md)

1. The proven answer decided last: most of 4 October went on where a click is counted.
2. Building before the shape was agreed: diagram first, a version switcher, the tests view rebuilt four times.
3. Telling the reader after a run instead of before, and advice that does not end.
4. A model that said false things; fix the model, not the card.
5. Checks that could only pass, and a stale suite reported "by design".
6. Seams between parallel helpers; contract first, then use the merged tree as a reader.
7. The box running out; at most four helpers, one browser each, everything under a lock.
8. Numbers that disagreed; one number, one source.
9. The board buried under text.
10. A brief that pointed at the wrong thing; his words win over the brief.

7. Proof on another problem

reference/dry-run-ticket-inventory.md: the seat-hold problem sketched under this playbook. The process carries over whole. Of its five tests, one would run on today's runner, and only in the URL's words. The rest need two keys per request, a conditional write "if free or expired", an all-or-none write, a transition on an existing record, and three new scenario events. Its heavy test needs a hot conditional write, which the model has no column for. That is the generalization above, named concretely.

Before you call a problem done

The ten lines at the end of reference/finished-problem.md, each with its check seen red once, the pictures opened at 1280, 1440, 1512 and 1728 (and 390 for the page), and a stranger's walk read.