I write specs in three steps:

1. Collect all input
2. Consolidate a cohesive list of requirements
3. Review & edit

Lately, I’ve added a few tools to my workflow to guide me through the process.

Collecting input

First, I gather every piece of input I can find: my own notes, Slack threads, Linear tickets… One of my most useful resources is Granola, which transcribes and summarizes every meeting I have. I organize projects into folders there, and before writing a spec, I’ll ask Granola to pull together everything it knows about the topic.

(All snippets in this post are based on the output I had writing a spec yesterday. I can't share it since it's client work, but I've reworked the examples to revolve around an invoice builder feature.)

Give me a detailed list of specifications of everything you know of the invoice builder.

I also use Monologue, a voice-to-text tool for Mac and iOS, to add extra ramblings.

Consolidating everything with a thinking model

Once I have everything in one place, I open my coding agent and attach everything. (Currently defaulting to Codex GPT 5.4 High for these kinds of tasks.)

A few things I’ve learned to always include in the prompt:

• Be explicit about who the spec is for. A spec for a designer should focus on UI patterns and how the feature fits existing conventions in the app. A spec for a developer should go deeper on the data model, potential abstractions, and how this interacts with existing parts of the system.
• Ask to compare notes and surface discrepancies. Notes accumulated over months are full of contradictions. One meeting says to build it one way; another says something different. I ask the model to flag these and grill me on them until the ambiguity is resolved.
• Ask to explicitly list what is in & out of scope. As I read notes I often skim over things that are implicitly out of scope for the project. But what I consider out of scope, someone else might have assumed was part of the project. AI is good at being critical about these small details.
• Reference the codebase. Look at what already exists for patterns we could reuse, and identify potential pitfalls based on existing functionality.

Some of these checks might seem obvious, but the more explicit you are towards the agent about your own process, the better your results.

If all goes well, you’ll be slammed with a few rounds of questions by the agent to refine the requirements and generate a final specification document.

This was my prompt yesterday:

I want to write a specification document for our designer to determine the UI and UX of the invoice builder. I want you to read all three documents I gave you. Grill me about anything that is unclear about the features or things across the document or even in the same document that contradicts each other. Grill me about anything that seems related to invoicing that is listed in documents but might not be part of this feature so we can decide to leave them out of the specs for now. Let's build a specification document together. Also look through the existing codebase and interface to understand the way products are set up and research potential pitfalls we could have implementing this in the existing system.

(text-to-speech, who needs newlines?)

Here’s a snippet of the output:

# Invoice Builder UI/UX Spec

## Purpose

Define the UI and UX for configuring and reviewing invoice templates, line items, and tax calculations within the invoice builder.

This document covers three surfaces:

- Organization-level setup
- Invoice-level review and override
- Discrepancy review and bulk reapply

This document is intended for product, design, and engineering alignment. It describes the behavior the interface must support, not the technical implementation details.

## Scope

### In scope

- Organization-level setup of tax rules, line item defaults, and payment terms
- Invoice-level display of the itemized breakdown associated with an order
- Invoice-level snapshotting from the organization template
- Invoice-level manual editing after snapshotting
- Visibility rules for clients, bookkeepers, and admins
- Discrepancy review UI for tax rate and line item drift
- Batch reapply flow from the current organization template to selected invoices

### Out of scope

- Payment processing or reconciliation
- Refunds
- Revenue recognition timing or accrual logic
- Report-generation workflows beyond discrepancy review
- Currency-specific tax logic
- Arbitrary reusable custom pricing objects
- Auditing payment term discrepancies

## Core Concepts

### Tax Calculation

Tax calculation is the applicable tax percentage for an organization in a given region or jurisdiction scope.

- Tax calculation belongs on the organization as a template
- Tax calculation is copied to the invoice when the invoice is created
- After the invoice is created, the invoice tax calculation is managed independently
- Clients should always be able to see their own tax breakdown
- Seeing the tax details of others requires a specific permission, which in practice is reserved for bookkeepers and admins
…

The content looks good on first sight but I don’t like the way it’s structured & formatted. Time to edit.

Reviewing & editing

At this point, I take a break from the AI tooling and re-read and edit everything in iA Writer. Most importantly, I ensure everything is correct & complete. Then I ensure the document is generally structured the way I want it to flow, cut noise & repetition, and ensure everything’s as clear as can be.

Then I throw it in Spiral for another edit. I like how Spiral lets you edit with AI without AI taking over your writing. Spiral allows you to define “styles”. I created a style based on previous specs I’ve written in the past so the specs can be re-edited into something closer to my voice.

Depending on who or what I’m writing the specs for, I sometimes prefer a “document style”, and sometimes a “single indented list” style. In Spiral, I have some predefined prompts to toggle between the two formats.

- In scope
    - Organization-level setup of tax rules, line item defaults, and payment terms
    - Invoice-level display of the itemized breakdown associated with an order
    - Invoice-level snapshotting from the organization template
    - Invoice-level manual editing after snapshotting
    - Visibility rules for clients, bookkeepers, and admins
    - Discrepancy review UI for tax rate and line item drift
    - Batch reapply flow from the current organization template to selected invoices
- Out of scope
    - Payment processing or reconciliation
    - Refunds
    - Revenue recognition timing or accrual logic
    - Report-generation workflows beyond discrepancy review
    - Currency-specific tax logic
    - Arbitrary reusable custom pricing objects
    - Auditing payment term discrepancies
- Core concepts
    - Tax Calculation
        - Applicable tax percentage for an organization in a given region or jurisdiction scope
        - Belongs on the organization as a template; copied to the invoice at creation
        - After creation, managed independently from the organization record
        - Clients can always see their own tax breakdown
        - Seeing another client's tax details requires a specific permission
…

When I’m done editing, I do one final review in iA Writer and it’s good to go.

Has AI made my output better?

Three or four months ago, without a model to consolidate & guide me with questions, writing this spec probably would have taken 3–4 hours. It took me about an hour and a half yesterday.

But the quality of my output hasn’t really changed much. AI models are good at surfacing small details that might otherwise be overlooked, but at that level of detail it makes things slightly better, not orders of magnitude.

What’s changed is that I’m never staring at a blank document. The tools give me structure to work reactively and keep working in flow.

Interview me relentlessly about every aspect of this plan until we reach a shared understanding. Walk down each branch of the design tree resolving dependencies between decisions one by one.

If a question can be answered by exploring the codebase, explore the codebase instead.

For each question, provide your recommended answer.

Incredibly simple, but the times I’ve used it so far it has been incredibly effective. (Almost annoyingly considering the amount of follow up questions you get; for a good cause!)

Current solves this with “the river”.

The main screen is a river. Not a river that moves on its own. You’re not watching content drift past like a screensaver. It’s a river in the sense that matters: content arrives, lingers for a time, and then fades away.

Each article has a velocity, a measure of how quickly it ages. Breaking news burns bright for three hours. A daily article stays relevant for eighteen. An essay lingers for three days. An evergreen tutorial might sit in your river for a week.

Outlets like The Verge have always been frustrating to follow with RSS because they generate 20+ posts a day and take over your feed. Essays from my favorite blogs often only appear once every few weeks and drown between the noise. The river balances them all out.

Current is made by Terry Godier. He also wrote a beautiful essay on the design decisions he made building it.

Don’t rely too much on permission or encouragement. […] instead of asking people for approval to go do something, you can just tell them what you intend to do (implicitly giving them space to object or course-correct if they feel strongly).

You can just do things.

Make success inevitable. There’s a huge difference between the following two operating modes:

1. My goal is to ship this project by the end of the month, so I’m going to get people started working on it ASAP.
2. My goal is to ship this project by the end of the month, so I’m going to list out everything that needs to get done by then, draw up a schedule working backwards from the ship date, make sure the critical path is short enough, make sure we have enough staffing to do anything, figure out what we’ll cut if the schedule slips, be honest about how much slop we need, track progress against the schedule and surface any slippage as soon as I see it, pull in people from elsewhere if I need them…

The hard part is being honest with yourself. I’ve often fallen into trap (1) because I’m afraid my plan will surface failure.

On taste:

I’ve noticed a lot of people underestimate their own taste, because they expect having good taste to feel like being very smart or competent or good at things. […] For this reason, the prompt I suggest here is: what does it seem like everyone else is mysteriously bad at?

Taste isn’t about being the best at something. It’s about slowly lifting the whole by leaving small things in better shape than you found them.

Early in the development process, when testing the incomplete application, I remembered that Subversion (the version control system after CVS, before Git) had a –dry-run option. Other linux commands have this option too. If a command is run with the argument –dry-run, the output will print what will happen when the command is run, but no changes will be made. This lets the user see what will happen if the command is run without the –dry-run argument.

I’ve added a --dry-run flag on scary destructive stuff I’m planning to run on prod. But not as often as I’ve wanted.

The downside is that the dryRun-flag pollutes the code a bit. In all the major phases, I need to check if the flag is set, and only print the action that will be taken, but not actually doing it.

This is one of the things that has become less of a downside with AI writing more code for us. AI helps us write code faster, but what especially entices me is having more breathing room to add affordances like this.

What the << operator does here [NewValue = OldValue << 2] is called bit shifting, meaning all the bits that store the value of the variable are shifted to the left, in this case by two positions, with the new digits being filled in with zeros. Since the number is stored in a binary system, every shift to the left means the number is doubled.

Since this is a lot faster than multiplication, Chris Sawyer decided to exploit this as much as possible:

The even more interesting point about those calculations, however, is how often the code is able to do this. Obviously, bit shifting can only be done for multiplications and divisions involving a power of two, like 2, 4, 8, 16, etc. The fact that it is done that often indicates that the in-game formulas were specifically designed to stick to those numbers wherever possible, which in most modern development workflows is basically an impossibility.

I do want to disagree with that last bit. Impossibility sounds too harsh. We can’t decide the requirements for stakeholders, but plenty of things aren’t as set in stone as they seem. It’s our job to nudge things in the right direction, so the result works with the grain of our programs.

There is a fundamental difference between relying on AI and leveraging it.

• Relying means assuming that if the agent wrote it and the tests pass, it’s ready to ship. The author never builds a mental model of the change. The result is massive PRs full of hidden assumptions that are impossible to review because neither the author nor the reviewer has a clear picture of what the code actually does.
• Leveraging means using agents to iterate quickly while maintaining complete ownership of the output. You know exactly how the code behaves under load. You understand the associated risks. You’re comfortable owning them.

I’ve seen a lot of strong opinions about disclosing whether code in a PR was written by hand or generated by AI. I don’t really care. The author owns the code in the first place. The author and reviewer have a shared responsibility for what happens on production.

Putting your name on a pull request means “I have read this and I understand what it does.” If you have to re-read your own PR to explain how it might impact production, the engineering process has failed.

The litmus test is simple: would you be comfortable owning a production incident tied to this pull request?

Most olive oil production at medium-or-greater scale depends on machines of this kind [over-the-row olive harvester]; they trundle over trees planted in long rows, almost like continuous hedges, and collect the fruit with vibrating fingers. Machine-harvested olives cost less to buy, and they arrive at the mill in better shape than olives harvested by hand.

The catch: most olives can’t be cultivated in this configuration; the trees don’t thrive so close together. Only a handful of varieties will tolerate it, so those handful have been planted in huge numbers, and the flavor of global olive oil has changed as a result.

AI enables us to do things faster, and sometimes better than we’ve been able to before. But it has its limits. And as we learn those limits, the work we do will shift to avoid them.

In a different section, the article dives into the limitations of the physical world.

The project cut across several different magic circles — Ruby code, quasi-governmental APIs, the rules and standards of the postal system — but/and it also broke out into the physical world of paper, printers, and post offices. The project required manipulations including but not limited to: folding, peeling, sticking … gnarly!!

It’s possible that an AI coding agent could have helped me with #1 above, and of course it could have advised me on the rest. But it’s impossible to imagine the AI agent handling #2-5 autonomously; it would require such a Rube Goldberg tangle of support that “autonomously” would no longer apply.

In our programming world, AI’s impact looks limitless. But once you drift outside the boundaries of software, it’s put into a different perspective.

If indeed AI automation does not flood fill the physical world, it will be because the humble paper jam stood in its way.

In practice, it has taught me to optimize for optionality, not efficiency.

The monolithic branch

To illustrate what it means, we’ll build a user account section as an example. The new account section will be shipped to users as one big launch. A user can…

• Update their basic profile information
• Add their address with Google Maps autocomplete
• Upload a profile picture
• Connect social login accounts
• Reset their password

Let’s make an estimate:

Summing up: 6 + 12 + 4 + 4 + 8 = 34, that’s a 40-hour estimate. (Gotta add that margin!) We’ll checkout a new feature/user-account branch, implement, and ship. The final logs in our time tracker:

3 + 14 + 6 + 18 + 2 = 43. Not too far off of our (padded) estimate! Some tasks were easier to implement than expected, some took a lot longer. But we didn’t ship 43 working hours later, it took 4 weeks to reach production. Why?

• We realized our application needed to be approved by our social login provider, that took a week. After that it took a lot longer than expected to implement.
• When we started to implement the new reset password flow we found a few issues in the design, so the design team had to update the Figma file. The implementation went smoother than expected, but we had to wait for the changes.
• Of course, the usual bugs and small feature requests that creep into our schedule pushed this project further down the road.

That users had to wait longer than estimated for the new account feature isn’t a problem. This post isn’t a manifesto to ship incremental changes over big bang launches—I’ll leave that decision to the product managers. Shoving everything into one branch is plain easy. Because we weren’t going to ship anything individually, we were allowed to! What I care about, is how it affects everything else. Because meanwhile…

• Another developer needed an address autocompletion on the shipping page. Now we have two implementations and need to trash one.
• Someone else refactored the user model and related code, causing a bunch of merge conflicts throughout the 4 weeks of development.
• Another timeline-like feature design relies on profile pictures, but we wanted to wait until this branch was merged so we had access to the profile picture components that are already set up.

Checkpoints

Let’s treat each task as an individual project. It will probably take longer—at least on our timesheet. We need to create a separate branch for every task and can’t implement changes in bulk. Instead of one big feature/user-account merge, we created, reviewed, and merged a bunch of smaller branches over the weeks.

feature/user-basic-information-views
refactor/share-google-maps-api-credentials
feature/google-maps-autocomplete
feature/profile-picture
refactor/user-authentication-changes
feature/social-login
fix/profile-picture-upload-bug
feature/reset-password-update
feature/reset-password-update-2

But what have we gained from this approach?

• If the address autocompletion was merged earlier, we wouldn’t have ended up with two implementations. Even if the first wasn’t shipped to production yet, it would have been a usable component in the codebase.
• We wouldn’t have spent as much time on merge conflicts because frequent merges keep them small or non-existent.
• We could have decided postpone social login if we knew it was such a big investment. We didn’t because it was too entangled in the monolithic branch.

Working towards mergeable chunks doesn’t only give the developer more optionality, it makes the entire organization more flexible.

Hindsight is 20/20. It could have gone differently: maybe working in the dark for a prolonged time didn’t affect anyone. But you never know this ahead of time. Priorities change, and you don’t have control of the external factors that force them to. If you were halfway the monolithic user account branch and a critical bug or competitor forces your hand, all of your code is held hostage until you get back to it. Even if you don’t release it to your users, it’s more valuable to have in your main branch.

When code is in a feature branch it doesn’t contribute to the rest of the codebase. This 40-hour project is an innocent example. We often fall into the same trap for 250-hour projects. That’s a month or two of work—a month or two of work in progress code dilly-dallying. Code rots over time. Work in progress code rots significantly faster.

To paraphrase Eliyahu M. Goldratt (I’m a sucker for the theory of constraints): large amounts of work in progress masks inefficiencies and bottlenecks in the production process. Reducing work in progress can improve cash flow. As work in progress is converted to finished goods and sold more quickly, it accelerates the cash conversion cycle. In our language: code only becomes an asset after it’s merged.

Action items

To make this plea actionable: treat each chunk of work as something that should be merged by the end of the week. That doesn’t mean it needs to be “done” or available to the end user, it needs to become a citizen of The Codebase.

The hard part is finding your checkpoints. Identify the critical path. What can you strip from a feature while keeping it useful? Do that last. take a step back every few hours, ask yourself what the least amount of work would be to make what you’re doing mergeable. Have a bug-free staging environment from day one and keep it that way to ensure frequent merges don’t affect quality (read about the broken window theory).

It takes a while to get used to, and will feel uncomfortable at first. But do this enough, and you’ll see checkpoints all over the place. Working in small chunks means individual tasks may take longer. But in the long term you and the team as a whole will see gains in flexibility, optionality, and efficiency. These benefits vastly outweigh the time you would win from a bulk discount.

Some desert wisdom to close:

Arrakis teaches the attitude of the knife—chopping off what’s incomplete and saying: “Now, it’s complete because it’s ended here.”