What I’m reading this week : Making complexity legible📚

date

Apr 24, 2026

slug

weekly-reads-April-25

status

Published

📚 What I’m Reading This Week: Making Complexity Legible

The three pieces I kept thinking about this week are all about legibility.

One is about making code review easier to digest. One is a catalog of the organizational laws that quietly shape software teams. One explains GPS from first principles, taking something we use every day and rebuilding it from time, distance, geometry, and relativity.

That feels like the common thread: progress often depends less on producing more information and more on making existing complexity consumable by the people who need to reason about it.

Code review as the next bottleneck

Stage is an interesting attempt at making code review easier to digest. The product frames itself around a simple idea: pull requests should be organized into logical chapters so reviewers can understand changes faster.

I think this is pointing in the right direction.

If AI makes it possible to ship far more software, code review becomes one of the obvious constraints. Not because humans are bad at reviewing code, but because the shape of the work changes. A reviewer is not just checking syntax. They are trying to reconstruct intent, understand risk, map implementation back to product requirements, notice architectural drift, and decide whether the change is safe to approve.

That is hard when the unit of review is a giant diff.

The answer is not simply faster reviewers or more rubber stamping. The answer is better packaging of software changes. Big pieces of code need to become easier to consume. Reviewers need narrative structure, smaller conceptual chunks, and clearer boundaries around what changed and why.

This is why I also think stacked PRs matter. GitHub's newer support for stacked changes is part of the same broader movement. The future of code review probably looks less like staring at one massive patch and more like walking through a sequence of focused changes where each step has a coherent reason to exist.

The deeper point is that the bottleneck in software may move from writing to understanding. If machines increase code production, teams will need much better tools for comprehension, trust, and approval. The winners will not just generate code. They will make generated work reviewable.

The laws underneath the meetings

Dr. Milan Milanović's Laws of Software Engineering is a useful collection because it names patterns engineers repeatedly rediscover the hard way. The site gathers 56 laws across architecture, teams, planning, quality, scale, design, and decision-making.

The two that stand out to me are Conway's Law and Goodhart's Law.

Conway's Law says that organizations design systems that mirror their own communication structure. This sounds abstract until you have worked inside enough companies. A fragmented org produces fragmented systems. A team split by platform boundaries often creates product seams that users can feel. A company that cannot coordinate well internally usually ships software that cannot coordinate well technically.

This is why architecture is rarely just architecture. It is a residue of how people talk, who owns what, which teams trust each other, and where coordination is expensive. You can sometimes refactor the code, but if the org chart and incentives stay the same, the system often grows back into the same shape.

Goodhart's Law is the other one I see everywhere: when a measure becomes a target, it ceases to be a good measure. This is especially relevant in engineering organizations because we love dashboards. Velocity, commits, PR count, story points, incidents, test coverage, operational metrics, AI generated code volume. All of these can be useful signals. All of them can become distorted the moment people are rewarded for moving the number instead of improving the underlying reality.

The lesson is not to avoid metrics. It is to treat them as instruments, not gods. Good metrics should invite better judgment. Bad metrics replace judgment with theater.

The best engineering leaders I have worked with understand both laws intuitively. They know that system design follows social design, and they know that incentives quietly rewrite behavior.

GPS and the pleasure of first principles

Shri Khalpada's How The Heck Does GPS Work? is the kind of explanation I always enjoy: take a technology everyone uses, strip away the magic, and rebuild it from first principles.

GPS is easy to take for granted. You open your phone, see a blue dot, and move on with your day. But underneath that blue dot is an absurdly elegant chain of ideas.

The piece starts with the simplest version: GPS turns time into distance. A satellite sends a radio signal. Your phone receives it. If you know how long the signal took to arrive, and you know the speed of light, you can estimate how far away the satellite is.

One satellite gives you a distance, not a location. You could be anywhere along a ring. Add more satellites and the rings intersect. That gets you closer to a point. Then the explanation adds the messier parts: your phone has a cheap clock, satellites have precise clocks, signal timing errors create huge distance errors, and relativity matters because satellite clocks experience time differently than clocks on Earth.

That is what makes the essay satisfying. It does not just say GPS uses satellites. It shows the stack of assumptions required to make the system work. Geometry gives you a framework. Time gives you distance. Better clocks reduce error. Relativity corrections keep the whole thing from drifting.

I like learning how things work because it changes how you see the world. A mundane object becomes a bundle of solved problems. The blue dot on a map becomes physics, engineering, incentives, infrastructure, and decades of accumulated precision.

In Conclusion

This week's readings all point to the same idea: modern life is full of systems whose main challenge is not only creation, but comprehension.

Code review needs to make large changes legible to humans. Engineering laws make repeated organizational patterns easier to recognize. GPS becomes less magical, and more impressive, when you understand the mechanics beneath it.

The questions I am sitting with:

What parts of software development are about to become bottlenecked by comprehension rather than production?

Which metrics in our organizations are still useful signals, and which have become targets people game?

And what other everyday technologies deserve a first-principles explanation so we can stop treating them like magic?