The written culture

Before the cheer feature was code, it was an argument. The argument is on file, which is the whole subject of this scene: at Traversal, and at every engineering culture that survives its founders, the arguments are on file. Deliberately. Forever.

Written how, and where. The heavyweight form is a technical specificationConcept · lights on your maptechnical specificationThe detailed what and how of something about to be built: interfaces, data shapes, edge-case handling. Written before code and reviewed like code. “Spec” in conversation., the what-and-how in detail before building. The reflective form is a design documentConcept · lights on your mapdesign documentThe why document for a significant choice: the problem, the constraints, the options considered, the tradeoffs, the recommendation. Circulated for written feedback before work begins., the why: options weighed, tradeoffs admitted. When a why is circulated for structured argument before deciding, it is an RFCConcept · lights on your mapRFCRequest for comments: a design document explicitly circulated for structured feedback before a decision. Named for the documents that define the internet’s own protocols., a name borrowed from the documents that define the internet itself, HTTP included.

One page, on file, forever

And when the decision is made, it gets a one-page memorial called an ADRConcept · lights on your mapADRArchitecture decision record: a short document capturing one decision after it is made. Context, decision, consequences. The codebase’s diary of whys, and the answer to next year’s “wait, why did we do it this way?”. Here is the one Finn wrote, nearly whole:

Context: cheers must reach runners without slowing the timing pipeline, and race-day traffic arrives in bursts. Decision: cheer delivery goes through a queue; the ingest path never waits on it. Consequences: delivery is fast but not instant; a delayed cheer is acceptable, a delayed split is not.

Read it twice. One act from now, when the mat gains its next layer of resolution, you will find this page printed on it: a row at 34 milliseconds, the write joins a queue, so nothing waits on what comes next. The mat is partly this piece of paper, grown up. Next year, when somebody new asks why cheers are queued, the answer will not be a shrug and a legend. It will be one page with a date on it.

The last written thing is a map of people. The repository carries code ownershipConcept · lights on your mapcode ownershipThe mapping of which team owns which part of the codebase, meaning their review is required to change it and their pager rings when it breaks. Enforced by files that assign reviewers automatically.: files that say the timing ingest belongs to Sam’s team and cheer delivery to Finn’s, with the one file where they meet claimed by both, enforced by machinery that auto-assigns reviewers. When Finn’s PR touched that shared file, that is how Sam appeared in the review, uninvited and exactly on time.

Written down: what, why, and whose. Next: where. Specifically, where Case has been this whole act.