How to write a technical spec as a product manager

How far should a product manager go into a technical spec?

Up to the edge of the system, and not one sentence past it. Everything a user, a partner or an auditor could observe is yours to specify: what happens, how fast, in what order, what the error says, what data survives. Everything that produces those observable results is engineering's, and the boundary is sharper than it feels in the moment.

Marty Cagan's framing of the four big risks is the cleanest test available. Value and business viability are product questions. Usability is design's. Feasibility, can we build this with the people and the systems we have, is engineering's call, and a product manager who answers it in a document has not saved anyone time. They have removed the judgement of the person best positioned to make it, and taken on a decision they will not be able to defend when it turns out to be wrong.

The practical version of the boundary: if two competent engineers could make a choice differently and no user would ever notice, it is not yours.

What you can specify, because it is visible from outside

Start with behaviour, stated as outcomes. What the user does, what the system does in response, and what is true afterwards. Then the four categories people skip, which are where most of the value of a product manager's spec actually lives.

Failure states, first. What happens when the third party is down, when the upload is too large, when the record was deleted between loading the page and clicking save. These are product decisions dressed as technical ones: whether a user sees an error or a silent retry is a choice about the experience, and if you do not make it, it gets made by whoever is writing the error handler that afternoon.

Then thresholds, stated as user-visible numbers rather than architecture. A page that loads in under two seconds on a mid-range phone. A search that returns within a second for a workspace of ten thousand records. An export that completes in a session or emails a link. Each is checkable and none prescribes how.

Then data. Which facts have to exist, what they mean in your domain, what is required versus optional, and what must never be lost. Not the schema. The vocabulary and the guarantees.

Then constraints from outside the team: the regulation, the contract, the platform you have to support, the language the interface has to exist in.

What belongs to engineering, and why writing it yourself is expensive

The database, the queue, the framework, the caching approach, the service boundaries, the retry policy, the index. Writing these in a product document has a specific failure mode that is worse than being wrong: it is being plausible. A senior engineer reading a spec that names a technology will usually assume there was a reason, and either follow it or spend a meeting undoing it. Both are worse than the spec not mentioning it.

There is a narrower case where naming a technology is legitimate: when it is a constraint rather than a choice. "This has to run on the existing billing service because finance reconciles against it" is a fact about the world. "Use Postgres" is a preference.

Acceptance criteria are yours; the team's definition of done is not. Atlassian draws the line usefully: acceptance criteria state what must be true for a specific story to be complete for the user, while definition of done is the broader quality bar the team holds across all development work, covering things like code quality and documentation. Writing the second one for the team is the same overreach as specifying the database, one level up.

The section product managers write best, and skip most often

Dependencies on other teams, with dates and named owners. This is the part nobody else will write, because nobody else has the cross-team view, and it is the part that most reliably determines whether a project lands.

Builders Camp's Project Management for Product bootcamp builds its practical challenge on exactly that gap. A B2B platform's Skills Passport launch slips 6 weeks, ships with half the features cut, and damages a key enterprise partnership. The original brief names the scope clearly, including what is out of scope, and then lists dependencies in a single line: an integration to be coordinated with a partner's team, a legal review of certification data storage, design complete by week 4. Every one of those is a commitment from someone outside the team, written as an assumption rather than as a scheduled item with a name attached. The post-mortem in the exercise is polite. The reconstruction is not.

Write dependencies as three columns in your head: what you need, who owes it, and by when they have agreed. A dependency with no agreed date is a risk, and it belongs in the risk list rather than the plan.

What goes wrong at the handover

Two failures, in opposite directions. The first is the spec that specifies implementation, which engineering either follows resentfully or rewrites, in both cases losing the week you spent writing it. The second is the spec that specifies nothing observable, arriving as a list of features with no thresholds, no failure behaviour and no data guarantees, which pushes every one of those decisions onto whoever is closest to the keyboard at the time.

The handover that works is not a document drop. It is the document plus a conversation where an engineer is invited to tell you which constraints are expensive, before anything is final. Nine times out of ten the two second threshold is free and the real cost is somewhere you did not think to ask about, which is information you can only get by asking.

Who this is for, and who it is not for

This fits a product manager working with an engineering team who wants their documents to be used rather than rewritten, which is the delivery half of what Builders Camp's Product Manager Foundations covers across 2 weeks and 4 live sessions, alongside discovery, prioritisation and metrics. Project Management for Product covers the dependency and risk work specifically, including how to plan without false certainty, and both sit inside the delivery path that the Product Delivery Specialist Track sequences. The story-level version of the same discipline is in the user story guide, and the document this spec sits underneath is the PRD.

It is not for a product manager on a team with no engineers. If you are building the thing yourself with AI tooling, the constraints document still matters but the handover does not, and the shape changes accordingly.

Ask which constraint is expensive, before you finalise anything

The habit worth building is one question, asked early enough to act on: of everything in this document, which line is the costly one? Engineers answer it accurately and almost nobody asks, because it feels like inviting a negotiation. It is usually the opposite. Most constraints cost nothing, one costs a month, and finding out which before the plan is committed is the cheapest hour available to you in the whole delivery cycle.

See the Product Manager Foundations bootcamp

For planning, dependencies and risk specifically, see the Project Management for Product bootcamp. For sequencing the work across a quarter, the product roadmap template.