Two Readers and a Red Box
A vision model read the top of my notebook page and filed it under a date eight years off, calmly. One reader cannot flag what it is sure of. So now two models read every page, and I look only where they disagree.
Legibility
Essays on making complex systems readable: loops, graphs, and the views a team is missing.
14 posts · all topics
A Loop Is a Path That Closes
One of my health checks stayed red for eleven weeks by reading its own failure. A loop is the special case of a trajectory, the path that happens to close, and a life does not.
Decan 12: Fix the Chassis, Not the Instance
Denebola marks the tail of the lion, and a tail moves before the body does. Decan 12 is reform and intuition: catching the map before it is gone, reading the anomaly instead of the object, and finding out that the fix almost always belongs at the chassis rather than on the instance in front of you.
The Loop Was the Top of a Stack
I typed my thirty-two loops, then drew them as a graph, and thought the loop was the top of the system. It turned out to be the roof of a stack eight floors deep, and the floor holding all the weight is the smallest one: the edge.
One Writer Per Artifact
Typing my automation handed me most of its rules for free; the type carries the contract. One rule came free with nothing, and it was the one my system was breaking: every file gets exactly one job that writes it. On the difference between rules you remember and rules the structure carries.
The View You're Missing Is the Graph
I gave every job in my automation a receipt, a health check, and a green light, and the system still would not fit in my head. A dashboard shows the state of the parts. The question I actually had was about the shape of the whole, and no amount of state answers a question about shape.
You Reinvented Data Engineering
The best thing anyone told me about my own system this year was that I had not invented it. The scripts I grew by hand are a data pipeline, the shape is a DAG, and the discipline is solved. What the tools actually sell, why I am not buying yet, and the difference between wanting an engine and wanting a map.
A Loop Is Seven Things
Thirty-two automated jobs run underneath my days, I wrote every one of them, and I could not hold the system in my head. The problem was never my memory. It was a word. "Loop" was one word doing the work of seven.
Why Thirty-Three Repositories Needed a Census
I had thirty-three git repositories and treated all thirty-three as if they were on fire. The fix was not more discipline or a better tool. It was a census: an inventory, an edge, and a rule for what counts as alive. Domain cartography applied to my own sprawl.
How to Map a Domain: The Six Layers
The hardest part of mapping a complex domain is the blank page. Here are the six layers I run every domain through, from primitives to levels, with the question each one answers, how to actually do it, and the failure mode that shows up when you skip it.
Domain Cartography
Domain cartography is the practice of charting a complex domain you have to live and act inside, until it is legible enough to navigate. Not making it simple. Making it readable. Here is the field, the method, and the six layers every map needs.
Making Complexity Legible: a beat-locked spit-rap on charting complex systems
Making Complexity Legible is Case I of The Cartographer of Complexity, a new Napkin Films series about Making Complexity Visible. The idea: you cannot make a complex system simple without deleting what made it work, so you do not shrink the sea, you learn to read it. A tidal-EDM spit-rap, Plan 9 and OG Bobby trading bars over recomposed Telemann, with a cartographer bunny who roams a sea that brightens as it becomes legible. CC BY 4.0.
Making Complexity Visible: You Cannot Simplify the Ocean, Only Chart It
When a system gets too big to hold, almost everyone reaches for the same move: make it simpler. It is the wrong move. You cannot simplify the ocean. You can only chart it. This is about the difference between simplicity and legibility, why decisions quietly migrate to whoever holds the context, and how to make a complex system visible enough to navigate without pretending it is small.
How to Live Coherently Inside Complex Systems
Coherent complexity is what you get when a complex system is made legible without being made simple. You do not reduce it. You map it, until you can move through it on purpose. A field guide to the practice, and the idea behind everything else I build.