Your product manager should not have to read diffs

There is a well-meaning piece of advice that circulates whenever a spec turns out to be wrong: the product manager should be more technical. Learn to read the code. Sit with the API. Then the gaps stop happening.

It sounds reasonable and it almost never works, because it misdiagnoses the problem. The gap is not that the product manager cannot read a diff. It is that the information they need does not exist in any readable form — in a diff or anywhere else.

What they are actually being asked to do

Take a request that touches an API, a web client, a mobile app and a background worker. To write a spec that survives, the product manager needs to know which of those four are affected, what already exists in each, what the change implies for the API contract, and what has to ship in which order.

None of that is in a single file. It is distributed across four repositories, in code written by three teams over two years, and the only way to extract it by reading is to already know where to look. "Be more technical" is not the missing skill. Knowing that push tokens live in a table created eighteen months ago by someone who has since left is not a skill at all — it is institutional memory, and it does not transfer by studying.

So what happens instead is the interrupt. The product manager asks an engineer. The engineer, who also does not remember, goes and reads. Two people now hold a fact that neither will write down, and the same question gets asked again next quarter by someone else.

The positioning that follows

If you accept that the missing thing is context rather than technical skill, the tool that fixes it is not a developer tool. It is a planning tool that happens to read code, and the difference shows up in every design decision.

The interface speaks product language. A feature request is written the way it was said in the meeting. If the system needs to ask a clarifying question, it asks about behaviour and scope, not about which service owns the write path.

Product and technical documents are separate outputs. Not one document with a technical appendix that the product manager skims past. Two documents, each complete for its own reader — because a shared document optimised for both is optimised for neither, and everyone ends up reading the half that was not written for them.

Source references are evidence, not homework. Every non-obvious claim carries a file path, a commit and a line range. The product manager is not expected to open a single one. They are there so the tech lead who doubts a paragraph can settle it in a minute instead of arguing about it in a meeting.

That last one is the load-bearing part. A generated document without citations is a confident stranger's opinion, and the correct response to a confident stranger is scepticism. A generated document where every structural claim points at a specific commit is something an engineer can falsify quickly — and a claim that can be falsified quickly is a claim worth arguing with.

Everyone gets their own output

The same analysis serves different readers if you stop pretending they want the same artefact.

• Product managers get a requirements document they can take into a prioritisation conversation without a translation layer.
• Engineering managers get the list of affected services and teams, which is the input to sequencing and staffing — and usually the first thing missing from a spec.
• QA engineers get test scenarios derived from the acceptance criteria, in the same pass, rather than three weeks later when the criteria have quietly changed.
• Tech leads and developers get a technical draft to verify and deepen. They are not the audience for the generated text; they are the audience for its citations.

Notice that developers are still in the loop, doing the part that needs them. What they are not doing is answering the same discovery question for the fourth time this quarter because it lives in their head and nowhere else.

The pricing tell

There is a giveaway that separates a planning tool from a developer tool, and it is not the feature list — it is who has to pay for a seat. A tool priced per developer is a tool that assumes the value is created by developers. If the point is that a product manager, an engineering manager and a QA engineer can each work from the same analysis, then the seat model has to include them, and reading has to be free. Someone who only reads documents consumes nothing.

Small detail, but it is the one that decides whether the product actually reaches the person whose problem it was. Tools with the wrong seat model get bought by engineering, used by engineering, and quietly become another thing product does not have access to.

None of this makes technical curiosity in a product manager a bad thing. It is a great thing. It just should not be a prerequisite for writing a spec that is true — and it should never be the answer to a question that four repositories could have answered by being read together.