Product Managers Are Writing Specs Against a Codebase They've Never Seen

The PM hands off the spec. Three days later, engineering comes back: "This will take three months. You're describing something that touches the billing service, the subscription service, and the notification queue — all in separate repos. Also there's already a partial implementation of this in the legacy admin panel that would need to be deprecated first." The PM had no idea. The spec was written blind.

This is not a rare failure mode. It is the default. Product managers are professionally responsible for defining what gets built, but the information they need to define it accurately — what already exists, what the architecture looks like, which services are involved, what constraints apply — lives in a system they have no practical way to access. The spec gets written against a mental model that is at best six weeks stale and at worst completely wrong.

The result is not just wasted planning time. It is a specific pattern of rework that happens after the spec is handed off, when the constraints the PM did not know about start surfacing one by one.

What a blind spec actually costs

The first engineering review of a blind spec almost never results in a clean kickoff. It results in a list of things the PM did not account for. Some are minor. Some require revisiting the entire scope of the feature. Most of them were knowable in advance — if the PM had had access to the right information.

The pattern looks like this: spec is handed off on Monday. Engineering reads it Wednesday. By Thursday, there are three Slack threads going about architectural complications. Friday's kickoff meeting turns into a scope negotiation that produces a revised spec. The revised spec goes back to stakeholders. Stakeholders have questions. The kickoff is rescheduled. This cycle repeats two or three times before the work actually starts, and by then the original timeline estimate is no longer valid.

Every iteration of this cycle costs about the same as the PM's original planning time. Multiply that by the number of specs that require rework, and the productivity loss in the product-to-engineering handoff becomes significant — not because either side is making mistakes, but because the PM lacked the system visibility to write an accurate spec in the first place.

Why PMs cannot see the codebase today

This is not about willingness. Most PMs would happily spend fifteen minutes exploring the codebase before writing a spec if fifteen minutes were actually enough. The problem is that every tool available for exploring a codebase was built for engineers — and using it effectively requires engineering judgment.

GitHub requires knowing which repository to look in, which branch is relevant, how the file structure maps to product concepts, and what a service boundary looks like in code. Cursor and Claude Code require the technical judgment to write prompts that will actually return useful results — a PM who types "how does billing work?" into Cursor is not going to get a useful answer without already knowing the vocabulary the codebase uses. Sourcegraph requires knowing the identifier or pattern to search for. All of these tools assume you already have a mental model of the system. If you did, you would not need the tool.

PMs do not know what they do not know. The information gap is not a matter of finding the right file — it is a matter of not knowing what questions to ask or what shape the answer should take.

The fifteen-minute problem

Research from product practitioners lands consistently on the same finding: a fifteen-minute codebase exploration before writing a spec eliminates most "this is more complex than you think" feedback from engineering. The constraint was knowable. The existing implementation was findable. The architecture dependency was visible. The PM just had no way to get there.

Fifteen minutes is the right unit. It is not a deep dive. It is not becoming technical. It is getting the answer to three or four specific questions before committing a direction to a spec document. Does this already exist in some form? What services would it touch? Is there anything in flight that overlaps?

The reason those fifteen minutes currently take three days of back-and-forth is not that the questions are hard. It is that the only available channel to answer them is asking an engineer who is doing something else. The answer waits for the next standup, the next Slack response, the next available slot on someone's calendar. Then the PM asks a follow-up question and the clock restarts.

What PMs actually need before writing a spec

The bar for PM system understanding is not high. It is not about reading source code or understanding implementation details. It is about getting answers to a specific set of questions that are completely addressable by anyone with access to an accurate description of what the system does.

Questions a PM needs answered before writing the spec:
  -> Does a similar feature already exist anywhere in the codebase?
     (currently: ask an engineer, or guess)
  -> Which services would this change touch?
     (currently: find out in engineering kickoff, after the spec is locked)
  -> What is the current behavior of the feature we're modifying?
     (currently: ask engineering, or write the spec against a stale assumption)
  -> Are there open Jira tickets that overlap with what I'm defining?
     (currently: search Jira manually, miss the ones named differently)
  -> What has changed in this area of the codebase in the last 30 days?
     (currently: ask in Slack, wait, get a partial answer)

What PMs currently have access to before writing:
  -> The last sprint's output
  -> Confluence docs that may or may not match current behavior
  -> Whatever came up in the last planning meeting

Every one of these questions has an answer in the codebase right now. The billing cycle behavior is there. The service dependencies are there. The open Jira epics are there. The recent changes to the relevant area of the codebase are there. The problem is not that the information does not exist — it is that there is no channel that gets a PM to that information in plain language, without an engineer intermediary, in under fifteen minutes.

The spec-to-engineering gap: four failure types

After looking at enough PM-to-engineering handoffs, the failure modes cluster into four categories. They are predictable, they are avoidable, and they all share the same root cause: the PM did not know a specific thing about the existing system when they wrote the spec.

Four types of spec failure that happen when PMs write blind:

1. Existing partial implementation
   Spec: "Build a bulk notification feature for admin users."
   Engineering kickoff: "There's already a batch notification job in the
   legacy admin panel — it covers 60% of this. We'd need to deprecate it
   before building the new one."
   Cost: 3 extra days of scoping, 1 sprint delayed.

2. Architecture constraint unknown to PM
   Spec: "Let users choose a custom billing cycle date."
   Engineering kickoff: "That requires a breaking change to the subscription
   service data model — billing_cycle is currently shared across all plans."
   Cost: Estimate triples. Stakeholder expectations reset.

3. Integration dependency unknown
   Spec: "Add a new payment method: bank transfer."
   Engineering kickoff: "Bank transfer goes through three separate provider
   APIs — Stripe ACH, the legacy bank connector, and a compliance webhook
   we maintain internally. Not one integration."
   Cost: 2-week estimate becomes 6-week project.

4. Jira collision
   Spec: "Build a user preference center for notification settings."
   Engineering kickoff: "There's an open epic in Q3 backlog that covers
   most of this. It's 40% done. Nobody told product it existed."
   Cost: Duplicate work discovered mid-sprint.

None of these represent a failure of product thinking. The PM in each case was doing exactly what they were supposed to do: defining the desired outcome, writing the requirements, scoping the work. The failure is that the scoping process happened without access to the system constraints that would have changed the scope.

What changes when the PM can ask the codebase before writing

Kognita gives PMs a plain-language interface to the actual codebase — not a general AI tool that guesses, but a managed index of the real system with answers grounded in what the code actually does. Before writing the spec, the PM can ask: does a notification service already exist? What does the billing flow look like end to end? Which services would a change to user preferences touch?

The answer comes back in plain English. No repository navigation required. No engineering vocabulary required. The PM asks the question in the way they would ask an engineer, and gets the answer in the way an engineer who was patient and available would give it.

Spec written blind (billing cycle feature):
  "Users can select a custom billing cycle date from their account settings.
   Default is the subscription start date. New selections take effect next cycle."
  -----
  Engineering response: "billing_cycle_date is a shared column on the
  plans table — not the subscriptions table. Every plan uses the same cycle.
  Changing this for one user means either migrating to per-subscription
  billing dates (multi-week schema migration) or adding an override table
  (2 weeks, but creates long-term debt). This spec assumes per-user dates
  are trivial. They are not."

Spec written with system grounding (same feature):
  PM asked Kognita: "How is billing cycle date stored, and is it per-user or
  per-plan?"
  Kognita: "billing_cycle_date lives on the plans table, shared across all
  subscriptions on that plan. There is no per-subscription override currently."
  -----
  Spec: "Users on individual plans can select a preferred billing date.
   Implementation note: billing_cycle_date is currently plan-scoped;
   this requires either a new billing_date_override column on subscriptions
   or a plan-level split. Engineering to assess migration path."
  Engineering response: "Great — you already understood the constraint.
  Let's go with the override column. Two weeks."
  Kickoff takes 20 minutes instead of 3 days.

The difference in the second spec is not that the PM became more technical. They asked one question before writing, learned one specific constraint, and incorporated it. The spec is better calibrated. The kickoff is shorter. Engineering does not have to spend time explaining a constraint that the PM should have known going in. The PM looks like they did their homework — because they did, in fifteen minutes, without interrupting anyone.

The question that changes everything

The single most valuable question a PM can ask before writing a spec is: does this already exist anywhere in the codebase? Not "has anyone built this before" — that is a memory question, unreliable. But "does the codebase currently have any capability that resembles what I'm planning to add?" That is a system question, and it is answerable with certainty if you have access to an accurate index of the codebase.

This question alone eliminates one of the four spec failure categories entirely — the "we already have 60% of this" discovery that happens in the kickoff meeting and blows up the timeline. It takes two minutes to ask. Currently it takes two weeks to discover.

Jira and codebase together: the combination that matters

The most valuable thing is not just codebase context in isolation. It is codebase context connected to Jira work-in-progress. A PM who knows what is in the codebase but does not know what epics are in the backlog touching the same area is still going to write specs that collide with in-flight work.

Kognita's Jira MCP integration closes this gap. The PM can ask: "Are there Jira epics that overlap with the feature I'm planning?" and get an answer that pulls from both the Jira backlog and the codebase index simultaneously. The collision between the new spec and the existing Q3 epic surfaces before the spec is written, not during the kickoff meeting three weeks later.

This matters most for organizations where Jira is used seriously — where epics span quarters, where work-in-progress is tracked, where there is real risk of two product tracks colliding in the same service without either PM knowing. The combination of Jira context and codebase ground truth is the only way to get ahead of that class of problem before it hits engineering.

This is a tooling gap, not a skills gap

A common response to the problem of PMs writing specs without system visibility is that PMs should be more technical — that good PMs read code, explore repositories, build enough engineering literacy to understand the system they are defining. This is well-intentioned and practically useless.

The PMs who already have this skill use it. The majority do not have the background, the time, or the organizational support to develop it. And more importantly: it is the wrong solution. The engineering literacy gap is a proxy for the actual problem, which is information access. The goal is not for PMs to become engineers. The goal is for PMs to get accurate system information before they write.

If a PM can ask a plain-language question and get a plain-language answer about system behavior, they do not need to read code. They need the answer. The code is just where the answer lives. Removing the engineering intermediary from that information flow is a tooling problem — one that is solvable without changing anyone's job description.

Final take

Specs fail not because PMs are bad at their jobs, but because they are asked to scope work without visibility into the system they are scoping against. The constraint they did not account for was in the codebase the whole time. The existing partial implementation was in the admin panel. The Jira collision was in the Q3 backlog. None of it was secret. All of it was inaccessible.

That is a tooling gap, not a skills gap. The fix is not a longer onboarding program for PMs or a new ritual where engineers walk through architecture before every spec. The fix is giving PMs a way to ask the system what it does before they define what to build — without needing an engineering degree to use it.