Field notes — the blog

Notes from inside the system.

Specific write-ups on decisions that moved the needle: architecture trade-offs, delivery pipelines, and leading engineers who are better than you at their part of it.

              {{ totalPosts }} notes
              {{ totalMinutes }} min total
              Monthly
            

/

                Latest
                {{ featured.date }}
                {{ featured.cat }}
                {{ featured.read }}
              

{{ featured.title }}

{{ featured.excerpt }}

Read the note →

// before → after
{{ row.text }}

{{ listHeading }}

{{ resultCount }}

                {{ post.cat }}
                {{ post.date }}
              

{{ post.title }}

{{ post.excerpt }}

{{ post.read }}

Nothing matches that.

Try a different term, or clear the filters.

The architect's dispatch

One note a month. Nothing else.

A single deep write-up on a system I worked on: the trade-off, the numbers, what I'd do differently.

            {{ article.cat }}
            {{ article.date }}
            {{ article.read }}
          

{{ article.title }}

{{ article.excerpt }}

{{ part.text }}{{ part.text }}{{ part.text }}

{{ b.alt }} — {{ b.caption }}

{{ b.label }}

{{ h.text }}

{{ cell.text }}

{{ b.label }}

{{ link.label }} {{ link.note }} {{ link.host }}

{{ b.caption }}

{{ b.text }}

{{ b.text }}

{{ b.label }}

{{ line.text }}

{{ item.no }}

{{ part.text }}

{{ part.text }}

{{ part.text }}

Takeaways

▖ {{ t }}

Tags

{{ tag }}

← Newer

{{ prevPost.title }}

Older →

{{ nextPost.title }}

Related notes

{{ post.cat }}

{{ post.title }}

{{ post.read }}

The bottleneck moved to review and nobody staffed for it

Leadership · Aug 2026 · 6 min read

My team writes considerably more code than it did a year ago and ships about the same amount. The constraint moved, and our process did not move with it.

Here is the uncomfortable measurement from last quarter. My team produced substantially more code than in the same quarter a year earlier, and shipped roughly the same amount of working software. Nothing was being wasted on the wrong things. The constraint had simply moved from writing to reading, and our process was still optimised for the old one.

Attention is now the scarce resource

Generating a 600-line change is close to free. Holding 600 lines in your head well enough to say whether they are correct costs exactly what it always did. When production goes up and comprehension does not, the queue forms at the reviewer, and the failure mode is not a slow queue — it is an approving one.

A pull request nobody has the energy to read is a liability with a green checkmark on it.

The three changes that helped

A hard size cap. Over ~400 lines a change gets split, no discussion. Beyond that our review quality falls off a cliff we can see in the defect data.
The description explains intent and rejected alternatives. The diff already says what changed; only the author knows what was considered and dropped.
Authors mark which parts they have verified themselves and how. Generated code that has not been executed is called out as such.

## what this is for
## what I considered and rejected
## how I verified it
   [ ] ran it against real data
   [ ] test added that fails without this change
   [ ] read every line I am asking you to read

That last checkbox started as a joke in a retro and turned out to be the most effective line in the file. Nobody wants to tick it dishonestly, and a few people stopped opening pull requests they had not fully read, which was the entire point.

The part I am still working on

Juniors used to build their mental model by writing the boring 70%. That work is largely gone, and the model it produced was not decorative — it is what lets someone look at a diff and feel that something is off. I have not solved this. What we do now is have them review more than they write, and defend the review out loud, which is slower and demonstrably better than the alternative.

The wider lesson is one every team hits eventually. Removing a constraint does not make the system faster; it relocates the constraint somewhere you were not measuring. If you have adopted these tools and your throughput has not moved, the queue has formed somewhere. It is almost always in front of a person who is reading.

Takeaways

When generation gets cheap, review becomes the constraint — measure it before you celebrate velocity.
Cap change size and require intent plus rejected alternatives in the description.
Make authors state how they verified the code, including whether they actually read it.

All notes · Shehzad Aslam