system-design-interview

Codebase → Staff-Level System Design Interview

Convert the repository in the working directory into a system design interview problem that a Staff/L6 candidate would be given, then answer it at that bar. The output is grounded in code that actually exists — not a generic template with the repo's name pasted in.

Modes

Read $ARGUMENTS. If empty, use brief.

Argument	Behaviour
(empty) / brief	Full 7-section interview brief. The default.
quick	Same 7 sections, one-third the length. Drop the as-built subsection and delta table from section 5, and the access-pattern table from section 6. Keep the target-design diagram — it is the highest-value element.
deep <topic>	Skip to section 7. Produce three bottlenecks on <topic> instead of two, each with the full failure math.
interview	Socratic mode. Emit sections 1–4 only, then stop and ask the user to propose a high-level design. Critique their answer against references/rubric.md, then reveal sections 5–7. Do not reveal the answer early.
save [slug]	Produce the brief, then write it to docs/system-design/<slug>.md in the repo. Full fidelity — real paths, real names. Stays local. See Phase 4.
contribute [slug]	Produce a redacted brief safe to publish, write it to docs/system-design/<slug>.shared.md, then offer to open the PR with scripts/contribute.mjs. Follows references/publishing.md exactly. See Phase 4.
similar	Recon only, then match this repo against the community library and report the closest problems. No brief. See Phase 5.
<path>	Scope recon to that subdirectory. Useful in a monorepo.

Any mode can be combined with an effort tier — quick scan, thorough, interview standard. If no tier is given, run Phase 0 and ask.

---

Rules of engagement

These are not style preferences. Violating any of them makes the output worthless.

1. Cite or don't claim. Every statement about what the code does carries a path/to/file.ext:42 reference. If you cannot cite it, you may not assert it.
2. Tag every assumption. Scale, traffic, team size, SLAs and business context are not in the repo. Write them as [Assumed] with a one-clause justification. Never present an assumption as an observation.
3. Name the crux. Every good interview problem has exactly one genuinely hard part. Find it and organise the whole brief around it. A brief where every section is equally weighted is a failed brief.
4. Cut complexity ruthlessly. Do not add Kafka, Kubernetes, a service mesh or a CQRS layer unless a numbered requirement in section 4 forces it. Every box in the architecture diagram must trace to a requirement ID. Unjustified components are the most common failure of this skill.
5. Take positions. "We could use Postgres or DynamoDB" is a junior answer. "Postgres, because the booking flow needs a multi-row transaction; revisit at 50k writes/sec" is the bar. See references/rubric.md.
6. No filler. If the repo has no async work, say so and move on. Do not invent a queue to have something to talk about.
7. Never open a secret. Do not read .env, key files, state files or credential stores — the deny-list is in references/recon.md and it is not negotiable. save writes full-fidelity output into the user's repository, so anything you read can end up committed. If you encounter a credential incidentally, record that it exists — "credentials hardcoded at config/settings.py:12" is legitimate findings material — and never reproduce the value.