In spec-driven development, the spec is where decisions live

Earlier this week, I was reviewing two specs that I co-authored with Claude Code. I thought I was being clever—I could simply run my /scope and /spec slash commands in two different sessions at the same time, then pass the spec files to my /code agents.

One spec said that when a call owner for a call that was automatically imported into OnePerfectSlice couldn't be matched to a user, the system should fall back to displaying their email. The other spec said the same field should return null. Both specs had been auto-approved. Both had valid pass markers. And both would have collided.

Good thing I double checked the specs. That ambiguity only surfaced because I took the time to carefully review what was generated.

That moment crystallized something I’d been circling for a few weeks: in an AI era where execution is cheap, the senior work isn’t just writing specs. It’s knowing which decisions have to be made first, and making sure dependent work doesn’t run ahead of them.

Why "we'll figure it out later" stopped working

In a lot of modern software teams, the full requirements never arrive complete. They get discovered mid-build: start coding, ship something, explore the codebase, iterate. “We’ll figure it out later” worked because iteration was bounded by the slowest part of the loop—humans writing and rewriting code.

That constraint has disappeared.

AI amplifies whatever you give it. Hand it ambiguity, and it will confidently generate one plausible interpretation at scale. Hand it a vague spec, and it will fill in the gaps with reasonable-sounding guesses. That old feedback loop—build, discover, revise—assumed execution was the expensive part and thorough discovery could happen along the way. Now execution is cheap and discovery is still expensive, except you’re paying that cost after having AI generate hundreds or thousands of lines of code. Ouch.

As Alexander Embiricos, who leads Codex at OpenAI, put it on Lenny Rachitsky’s podcast: “A current underappreciated limiting factor is literally human typing speed and human review speed.” When execution outpaces our ability to review and reason, ambiguity doesn’t get corrected. It gets multiplied.

What a spec actually is (and isn't)

So what's a spec really? A spec is not documentation. It's not a record of decisions for humans to read later. It's a forcing function that collapses "maybe" into "yes" or "no" before you've committed to a path.

When I found the inconsistency between those two specs—D1 using email fallback, D2 returning null—I couldn't leave "name resolution" as a vague concept anymore. My /redteam review came back with a HIGH priority flag: "Inconsistent name resolution behavior between D1 and D2. Update D2 to match D1's email fallback pattern." That wasn't a suggestion. It was a decision that could no longer be deferred.

The spec is where decisions survive the pressure to postpone them. Every time you write "handle appropriately" or "determine at implementation time," you're not saving time—you're borrowing it at interest.

Where judgment now lives

Here's the shift that took me a while to internalize: the spec didn't make the work easier. It made the judgment explicit.

In one security-sensitive spec, we had to decide how to validate that logs never emit external URLs. The obvious answer was automation. Write a test, run it in CI, done. But when we actually tried to formalize the requirement, we realized automation couldn't prove the negative. The spec forced us to add a manual review step. Not because we wanted to, but because writing it down made us confront what we were actually promising.

The judgment got explicit. The spec became the contract for how we'd keep security intact. That decision—manual review for this specific check—would have been hand-waved in implementation. "We'll figure out how to verify this later." But later never comes with the same rigor as the moment when you have to write it down.

This is why specs feel harder at first. You're doing the cognitive work you used to defer. But once that work is done, execution gets calmer. The questions that used to surface during implementation have already been answered.

Why this is a new senior skill

Junior engineers can execute. They can take a well-defined problem and solve it. That's always been true, and AI makes it more true execution is getting automated an an increasingly alarming rate.

Senior engineers collapse ambiguity. They take a vague problem and turn it into a well-defined one. That's where the leverage is now.

In one spec, I had to make a concrete decision about sorting. The system needed to sort call records by the owner's name, but "name" could mean the user's full name or, if no user was found, an email fallback. In the old world, I would have written "sort by owner name" and figured out the edge cases during implementation, while testing it. In the new world, that ambiguity would have propagated into generated code, test fixtures, and UI assumptions. All of it built on a foundation I hadn't actually decided on.

The spec forced the decision: server-side sorting by resolved name, with explicit null-handling rules. It felt pedantic at the time. It saved hours later.

The job is no longer "doing." It's deciding what to do, in enough detail that execution becomes mechanical.

What you can't postpone anymore

The questions that used to hide in implementation are now expensive to discover late.

I watched a PR fail last month purely because the spec's test requirements weren't translated into code. The spec had pinned down exact scenarios: a race condition where ten concurrent requests hit the same endpoint, and exactly one should succeed while nine return "already exists." The /redteam produced a fixlist: "Missing integration test file. Add three tests. Verify exactly 1 returns Created and 9 return AlreadyExists."

That specificity existed in the spec. It didn't exist in the code. The gap between "we defined this" and "we built this" became visible in a way it never would have when humans were writing all the tests by hand.

The cost of "we'll figure it out" is no longer hidden in slow iteration cycles. It's visible in failed reviews, in inconsistent behavior across specs, in the compound interest of deferred decisions.

If you're still waiting for execution to reveal requirements, you're already behind. The work didn't get easier. Judgment and decisions just got explicit. And the people who can collapse ambiguity into specs before execution starts are the ones whose leverage is growing.

The spec is where invisible work becomes explicit. That's where senior judgment lives now.

Every function now needs the same thing engineers do: a way to prevent ambiguity from scaling.