Spec Writing and Engineering Handoff That Doesn't Bleed

Your last spec was eight pages. Engineering opened it once on Monday, skimmed the headers, and never reopened it. By Thursday, two stories were stuck because nobody knew whether the export should include archived records. By the next sprint review, 40% of the work had been reworked. You got blamed for spec sprawl. Engineering got blamed for not reading. Nobody fixed the system.

That's the loop. This is how to break it.

Why your last spec didn't get read

I've watched this play out on three teams in the last year. Each one had a different stack, different domain, same pattern: the PM produces a long spec, engineering produces a long sprint, and the gap between what was written and what was built is filled with rework.

The 40% rework number isn't from a survey. It's what teams find when they actually count. Pull your last sprint's tickets, mark every story that changed scope, got a follow-up ticket, or shipped with a known bug that traced back to "we didn't know that." That's your rework rate. Most teams who do this exercise honestly land between 30 and 50%.

The spec didn't cause this alone. But the spec is the cheapest place to fix it. Code is expensive to rewrite. A doc is free to rewrite, and a 1-page doc gets rewritten a lot more than an 8-page one.

Here's what we're replacing the novel with.

The 1-page spec

Seven sections. Each one earns its place. If a section isn't doing real work, it doesn't go in.

# [Feature Name]

**Problem**
What's broken or missing for the user. One sentence. Real user, real pain. Not "users can't do X." More like "Sales reps can't export their pipeline to share with their manager before 1:1s, so they screenshot it and paste into Slack."

**Hypothesis**
If we ship [thing], then [outcome] will happen, because [reason]. One sentence. This is what we're betting on.

**Success Metric**
The one number that tells us we won. Not three. One. Be specific: "30% of sales reps who view their pipeline use Export within 14 days of release." Add a leading indicator if the lagging one takes too long to read.

**Scope**
What's in. Bullet list, max 7 items. Each bullet is something a user can do or see.

**Anti-Scope**
What's NOT in, even though someone will ask. Bullet list. Be specific: "Custom export templates — not in v1. Scheduled exports — not in v1. CSV column reordering — not in v1." This is the section that saves your sprint.

**Edge Cases**
The five things that will break if we don't think about them now: empty states, errors, large datasets, permissions, concurrent edits. List the actual ones for this feature.

**Open Questions**
The decisions we don't have answers to yet, with names attached. "Does the export include archived deals? — @ravi to confirm with sales ops by Wed."

That's it. One page. The whole spec.

The killer feature is anti-scope. Most PMs skip it because it feels negative or because they think "obviously we're not doing X." It's never obvious to engineering. It's never obvious to design. It's never obvious to the stakeholder who DMs you on Friday asking why their pet feature isn't in. Anti-scope is the section you point to when someone tries to expand the work mid-sprint. Without it, you're arguing from memory. With it, you're pointing at a line that everyone signed off on two weeks ago.

I've shipped features without anti-scope and ended up rebuilding the export flow twice because the first version assumed unfiltered data and the second was retrofit to handle saved filters. Two engineers, three weeks. All saved by a 4-bullet anti-scope section that took 90 seconds to write.

The pre-spec eng review (15 minutes)

The spec doesn't go from your laptop to Jira. It goes through a 15-minute eng review first, and you bring a draft, not a finished doc.

The setup:

• Who: Tech lead, one senior engineer, you. That's it. No designer yet. No PM peer. No manager.
• When: Before you've shown the spec to anyone else. Before design has started. Before stakeholders have weighed in.
• What you bring: The 1-page spec, marked DRAFT. The Problem and Hypothesis sections are firm. Everything else is bait.
• What you get: A list of edge cases you missed, a rough sense of effort, and an early "this is the wrong approach" if it's the wrong approach.

The agenda, kept on a sticky note:

0–2 min:  Problem + hypothesis (you talk)
2–8 min:  Eng pokes holes in scope and edge cases
8–12 min: Eng floats two or three implementation directions
12–14 min: Open questions, who owns each
14–15 min: "Are we directionally good?" — yes/no/maybe

If the answer is "no" or "maybe," you don't write more spec. You go fix the problem framing or the approach. Most spec problems are framing problems wearing a costume.

The reason this works: engineering reviewing a half-baked spec gives you their best thinking before they're in defensive mode. Once a spec is "finished," the review turns into a critique of your work. When it's a draft, you're co-authoring. The same engineer who would have written a 12-comment shred-job in Jira will instead say "what if we just added a flag to the existing export endpoint?" and save you a week.

The kickoff doc

Once the 1-page spec passes pre-spec review and design has weighed in, you write the kickoff doc. This is what gets pinned in the team channel. It's a contract.

Four sections, each one short:

RACI table — one name per role

A committee is not accountable. One name is.

If you can't fill the Accountable row with a single name, the project isn't ready to start.

Milestones with dates

Three or four milestones. Real dates. Not "end of sprint."

• Mar 14: Design ready, dev starts
• Mar 21: Backend endpoint behind feature flag, internal test on staging
• Mar 28: Beta with 10 customers
• Apr 4: Demo day (non-negotiable)
• Apr 11: GA

Demo date — non-negotiable

Pick a date. Tell the team. Tell the stakeholders. Tell yourself you will demo whatever exists on that date, even if it's ugly.

Demo dates that move are not demo dates. They're aspirations. Ship what you have. If what you have is half a feature, demo half a feature and explain what's left. That's how trust gets built. The team that demos every two weeks even when it's rough always ends up faster than the team that demos when it's polished.

Kill criteria

This is the section nobody wants to write and everyone needs.

"We will stop building this if: beta customers don't use the export within 7 days of activation, OR backend latency exceeds 800ms at p95 with our test dataset, OR more than two customers report data accuracy issues during beta."

Three conditions. Concrete. Measurable. Pre-committed.

Without kill criteria, every feature lives forever. With them, the team has air cover to call it. I've killed two features in the last 18 months using this section, and both times the engineers thanked me. Nobody wants to spend three more weeks on something that isn't working. They just need permission, in writing, set in advance.

Loom > meeting (mostly)

The handoff meeting where you walk engineering through the spec for 30 minutes? Skip it. Record a 4-minute Loom instead.

What goes in the Loom:

1. The 1-page spec on screen, you talking through it.
2. Two demo flows: the happy path and one edge case.
3. The three things you most expect to be questions.
4. A sentence at the end: "Drop questions in the thread, I'll respond by EOD."

What this gets you: engineering watches at 1.5x speed when they're ready, not when your calendar is. Questions go in a thread, which means everyone sees the answer once instead of you re-explaining the same thing in three Slack DMs. New engineers joining the project two weeks later watch the same Loom instead of pulling someone aside.

When Loom doesn't work: when the project is genuinely ambiguous and the team needs to argue out loud. When trust is low and async feels like the PM is hiding. When there are real strategic trade-offs that need a room. For those, do the meeting. For everything else, Loom.

The "it's done" definition

Acceptance criteria written as "user can log in" is not acceptance criteria. It's a wish.

Use Given / When / Then. Concrete examples, real data, real states.

Bad:

User can export pipeline.

Good:

Given I am a sales rep with view access to my pipeline, And I have applied a filter showing only deals owned by me with stage = "Negotiation," When I click Export and select CSV, Then a file downloads named pipeline-2026-04-28.csv containing exactly the deals visible after the filter, with columns: Name, Stage, Amount, Close Date, Owner.

Edge case (empty result): If the filter returns zero deals, show a toast: "No deals to export," and do not download a file.

Edge case (large dataset): If the filter returns over 10,000 deals, queue the export and email the file when ready. Show a toast: "Export queued. We'll email it to you."

That's two more minutes of writing. It's three days of saved arguments. The QA engineer reads this and writes a test. The backend engineer reads this and knows the endpoint contract. The customer success lead reads this and knows what to tell beta customers. One artifact, four jobs.

Don't skip the edge cases. The edge cases are where the rework lives.

Post-ship retro template

Twenty minutes. Five questions. Posted in the team Slack channel within a week of GA.

**[Feature name] — Post-Ship Retro**

1. What was unclear in the spec?
   (One bullet per person, no debating, just listing.)

2. What did we miss in scoping — what showed up that we didn't plan for?
   (Effort, risk, dependency, anything.)

3. What rework happened, and why?
   (Be specific. "Rebuilt the filter persistence twice because we didn't decide on URL vs. local storage early enough.")

4. What edge case bit us?
   (The one we wish had been in the spec from day one.)

5. What goes into the next spec?
   (One concrete change to the template or the process.)

— Replies in thread by Friday. I'll summarize and post the next-spec changes Monday.

The point isn't blame. The point is to evolve the template. The next spec gets one upgrade. Then the one after that gets another. Six months in, your team's spec process is materially better than where it started, and nobody had to sit through a 90-minute retro to get there.

I keep a running file called spec-improvements.md with one bullet per retro. It's two screens long after a year. It's the most valuable document I own.

Common anti-patterns to watch

A few patterns that show up over and over. Name them out loud the moment you see them. They die when named.

• The "design tossed it over the wall" handoff. Design finishes, drops a Figma link in the spec, vanishes. Engineering hits an interaction the mocks don't cover, asks design, gets "use your judgment." Three days later it ships wrong. Fix: design joins the kickoff. Their RACI row is "Consulted" with a name attached. They're on call for interaction questions for the first sprint.

• The spec that grows during the sprint. Stakeholder DMs you on Tuesday. "Hey, can we also add X to this release?" You say yes because saying no feels political. By Friday the team is behind. Fix: anti-scope. Point at it. "X is in v2. I logged it." Done.

• The missing anti-scope. Engineering builds the feature, then asks "what about archived records?" You say "great question, let's add that." That's anti-scope leaking back in as a Trojan-horse question. Fix: anti-scope is in the spec from day one. Anything not on the in-scope list is, by default, out.

• The demo-day surprise. Demo day arrives. The PM hasn't seen the build since Monday. Half the flows don't work the way the spec said. Stakeholders walk away confused. Fix: PM does a private walkthrough with the engineering lead 24 hours before demo day. Mismatches get caught when they're still fixable.

Closing

A spec is a contract, not an essay.

The 1-page spec is short because short specs get read. The pre-spec eng review is 15 minutes because anything longer becomes a meeting nobody wants. The kickoff doc has one name per role because committees can't be accountable. Loom replaces the walkthrough because async writing scales and meeting calendars don't. Given/When/Then exists because "user can log in" has shipped a thousand broken logins.

Anti-scope and kill criteria are the two sections most PMs skip and most regret skipping. Don't skip them. They're the cheapest insurance you'll ever buy.

Shorter, sharper, signed off. That's the whole game.

Learn More

• Product Manager Job Description
• Running Sprint Planning That Doesn't Drag
• Roadmap Communication for Cross-Functional Teams
• Working with Design: PM and Designer Handoff