Notes

Teaching preferences

Explicit request: teach through real, known big-tech solutions. Every lesson must centre on a documented system from a real company. Invented toy examples are allowed only as the "your world" bridge at the end.
Drivers: tech-lead scope (design docs, design review, arguing trade-offs) + genuine curiosity. No deadline, so favour desirable difficulty and spaced retrieval over coverage speed.
Starting floor: comfortable with API + DB CRUD. Assume zero hands-on with sharding, replication, queues, multi-region. Do not assume the meaning of terms like quorum, LSN, or p99 — introduce or link them.

Working notes

Works across a frontend and a backend repo (paths are in the private global config, deliberately not recorded here). Not yet inspected. Worth reading before a lesson that wants a real "apply this to your system" exercise — ask first, since the mission is about judgement, not refactoring their repo.
Global CLAUDE.md asks for caveman mode in chat. Lessons themselves are written in full prose — chat is terse, teaching material is not.
Heads-up recorded: a grill-with-docs skill is named in the global CLAUDE.md but is not installed here. The installed equivalents are grilling / grill-me. Worth wiring up later — grilling a design is exactly the tech-lead skill this mission targets.

Lesson ladder

Superseded by CURRICULUM.md (13 weeks, ~120 lessons, 1–3/day) as of 2026-09-22. Original provisional ladder, now complete:

✅ Replication lag & read-your-writes (Facebook memcache) — the first thing that breaks past one DB.
Cache invalidation, leases, thundering herd (Facebook memcache §3.2) — interleaves with 1.
✅ Partitioning, hot partitions & tail latency (Discord 2017 + 2023) — lesson 0002, built 2026-09-20. Interleaves lesson 01: quiz re-tests idempotence and replication-vs-partitioning.
✅ Leases & the thundering herd (FB memcache §3.2.1) — lesson 0003, built 2026-09-21. Interleaves lessons 01 and 02 (three of six quiz questions reach back).
✅ Timeouts, retries, backoff, jitter (AWS Builders' Library) — lesson 0004, built 2026-09-21. Carries the COLD re-test of lesson 01 (staleness ladder + idempotence). Result not yet known.
Quorums & availability trade (Dynamo).
Sharding a live Postgres with 5 minutes of downtime (Notion) — pairs with lesson 02's partitioning. Spacing: re-test lesson 1's read-your-writes inside lesson 3 and lesson 5, not immediately after.

Lesson-writing shape (from LR-0003)

Every case study follows: problem → topology chosen → alternatives rejected + their prices → mechanism → residual risk. Describing a mechanism without justifying the topology under it reads as hand-waving to him.

Reference stack

PostgreSQL (latest — 18) is the reference implementation for database mechanics, per his request (2026-09-20). Explain WAL, LSN, synchronous_commit, walsender/walreceiver in Postgres terms; mention MySQL only where a case study (e.g. Facebook) actually runs it. Always cite postgresql.org/docs/current.

Recurring question shape

He asks "why X and not Y" about tool choices (memcached vs Redis, 2026-09-20). Answer these with date + what the team already owned + what they were willing to fork, not a feature table. Path dependency is usually the real answer, and naming that is itself the tech-lead skill this mission targets.
Never name the employer, its products, repo paths, or any other personal/organisational detail in ANY file in this repo — it is public. Reaffirmed 2026-09-23 after the org name was found live on the site. Keep the "apply it to your world" sections generic — "a system like yours", "most systems". Workspace files (MISSION, NOTES, records) still hold the context for steering; the teaching material stays neutral.

Spacing ledger

Lesson 01 quiz: 6/6 first try, same sitting (fluency only). Read-your-writes + the ladder still owe a COLD re-test — schedule inside lesson 04 and again around lesson 06.
Lesson 02 quiz interleaves lesson 01 (idempotence, replication vs partitioning). Do not re-explain those in future lessons; re-test them.

Pace change (2026-09-22)

Target: 1–3 lessons per day for three months. Full plan in CURRICULUM.md, grounded in four syllabi — DDIA 2e, MIT 6.5840, the Google SRE book, and the AWS Builders' Library — plus first-party blogs.
Lessons 01–08 built and complete, with seven reference sheets.
Standing rule for the batch work: no lesson ships without a named primary source fetched and quoted. If a source cannot be verified, the lesson waits and the gap goes in CURRICULUM.md's gap list.
Risk to watch: generating ahead loses the tuning that made lessons 01–02 good (they grew ~3x from his questions). Mitigation — write in small batches, and revise earlier lessons when his answers reveal gaps.

Site (2026-09-22)

The workspace is an Astro site: npm run dev, npm run build, npm run check.
Lesson and reference .html files under src/content/ stay the source of truth and remain valid standalone documents. src/lib/content.js parses them at build time — lifts <main>, the page-specific <style>, a heading outline for the table of contents, and rewrites relative links onto site routes.
So: keep writing lessons exactly as before. Add a file to src/content/lessons/, and the sidebar, the contents panel, the prev/next pager and the home page all pick it up with no other edit.
Run npm run check before every push; it catches quiz imbalance, dead links and SVG entity bugs.

Batch generation (2026-09-23)

Lessons 09–18 were written by ten parallel subagents, one per lesson, each given the house style, a named primary source to fetch and quote, the quiz rules, and the validator to run on its own file.
It worked, with supervision. Independent check afterwards: 114 quoted fragments extracted from the ten lessons and substring-matched against the actual source text (RocksDB wiki, PostgreSQL docs, ClickHouse, Parquet, Protobuf, Avro). Zero fabricated quotes. One real defect: lesson 16 joined two sentences that sit 466 characters apart in the source with no ellipsis — fixed.
Agents self-corrected usefully: several found that WebFetch paraphrases and switched to curl + tag-strip for verbatim quoting; one caught a brief of mine pointing at the index fillfactor doc when the HOT mechanism needs the table one; one caught its own illustrative numbers being mistaken for a source's worked example.
Keep for future batches: ten is the right size — it is the number that can still be reviewed properly. Always run the independent quote check; the agents' own reports are not evidence. Do not edit an agent's file while it is still running — mid-write validator output is misleading.
Prefers sequence diagrams (stated 2026-09-23). Default to lifelines + time-downward + labelled message arrows whenever the idea involves ordering, protocol, or failure timing. Space-time diagrams for logical clocks are the same idiom and count. Use another form only for genuinely non-temporal ideas (disk layout, containment, a decision fan).
Batch 2 (lessons 19–28) verified the same way: 137 quoted fragments matched against source text. Zero fabrications. Every apparent mismatch was my own checker — PDF hyphenation across line breaks ("par-tial", "al gorithm", "pat terson"), smart quotes, and a bad anchor search. Lesson 19 quotes a 1987 scan whose OCR renders "is" as "1s" and "might" as "nught"; the agent reproduced it exactly and said why. Lesson for the checker: de-hyphenate before comparing, and never label a miss a fabrication without grepping the raw source.
Batch 3 (29–38) verified: every quoted fragment matched to source. Agents independently discovered and routed around three broken sources — the Spanner PDF 404s through r.jina.ai because the proxy collapses a double slash (curl preserves it); the AWS Builders' Library now lives on builder.aws.com behind content IDs; kafka.apache.org/documentation/ is a JS redirect stub and the prose lives under /43/
/. tools/verify-quotes.py now does this check reusably — it folds PDF hyphenation, ligatures, smart quotes and both Greek epsilons, and prints "suspects, not verdicts" because every miss so far has been extraction.