The Spec Nobody Reads
At Salesken, I watched the same pattern repeat weekly: a PM would spend two hours writing a spec, engineering would read it in eight minutes, and then rewrite half of it because the spec was missing codebase context — which services are affected, what the dependency graph looks like, what broke last time someone touched that module. The PM wasn't wrong. They just didn't have the information that lived in the code.
It's 2 PM on Tuesday. You've spent the last two hours researching a bug report, gathering context from Slack threads, and writing what you think is a comprehensive spec. You include acceptance criteria, user impact, and three possible implementation paths.
Engineering reads it in eight minutes and starts rewriting.
Not because you're a bad writer. Not because the spec is unclear. But because you're missing something critical: context about the actual codebase.
You don't know which files this bug touches. You can't see the error logs. You haven't traced through the architecture to understand why this is happening. You're writing a spec based on 40% of the information that exists about this problem.
Meanwhile, your engineers—who do have that context—have to rebuild your entire analysis from scratch. They re-read the bug report, dig through git history, check the logs themselves, trace the bug to three files they've touched before, and realize your proposed solution wouldn't work because of a database constraint you didn't know about.
This isn't a writing problem. It's a context problem.
And it costs your team time. In my experience, PMs spend about 40% of their productive time writing specs that engineering effectively rewrites. That's not a productivity hack to microoptimize—that's a structural inefficiency that eats half your PM capacity.
The fix isn't better writing tools or more detailed templates. The fix is giving PMs (and AI agents writing on their behalf) access to the context engineers already have.
That's what AI spec writing does.
Why Engineering Rewrites Your Specs
Let's be honest about what's happening when a spec gets rewritten.
Your engineers aren't being difficult. They're not dismissing your work. They're solving a fundamental information asymmetry.
When you write a spec without codebase access, you're writing blind to:
What files actually need to change. You might propose a solution that requires modifying a legacy service that nobody wants to touch, or you might suggest a refactor that's already in progress on a branch. You don't know because you haven't searched the codebase.
What constraints already exist. There's a database schema limitation. There's a third-party API integration that doesn't support what you're proposing. There's an undocumented dependency between two services. None of this is in a README—it lives in the actual code, the error logs, and in your engineers' heads.
How users are actually interacting with this. You have the bug report ("things are slow"), but you don't see the analytics. Is this affecting 0.01% of users in edge cases, or 8% of your core user base? Is it causing support tickets or just forum complaints? Engineers dig into this because spec impact matters, but you can't without access to the data.
What's technically feasible in your architecture. Some solutions are elegant in theory but would require rewiring core systems. Others are technically straightforward but would create cascading problems elsewhere. You can't know which is which without understanding your tech stack.
So engineering reads your spec, finds the context gaps, and does the real analysis work themselves. The spec you spent two hours on becomes reference material. The spec they write—drawing on architecture knowledge, codebase patterns, and constraint awareness—becomes the actual source of truth.
This isn't failure. It's normal. But it's also expensive.
What AI Spec Writing Actually Looks Like
Here's the difference when an AI agent writes the spec instead.
The bug report comes in: "Dashboard is loading slowly for users with 10K+ customizations."
An agent with codebase access doesn't start from zero. It:
Reads the error logs. Finds that dashboard API calls are timing out. Traces the timeout to a N+1 query problem in the customization loader.
Searches the codebase. Identifies three files: dashboard_api.py, customization_loader.py, and db_schema.sql. Sees that this same pattern has been refactored in the admin panel recently—there's already a precedent for the fix.
Checks the analytics. Discovers this affects 4.2% of active users, concentrated in enterprise accounts. Revenue impact is real.
Understands the constraints. Sees that customization_loader.py is used in three places, not just the dashboard. Notes that a naive refactor would break the mobile app unless coordinated carefully.
Knows the architecture patterns. Recognizes that your codebase uses Redis for caching in the billing service and the settings service, so a similar pattern should work here. References similar implementations.
Produces a spec that includes:
- Root cause (N+1 query in customization loading)
- Which files change (specific to your codebase)
- Why naive solutions don't work (references your specific constraints)
- The recommended approach (using your existing patterns)
- Implementation sequence (mobile app coordination required)
- Rollback plan (specific to your infrastructure)
- Success metrics (specific query time targets + analytics thresholds)
When your engineers read this spec, they nod. They might adjust the implementation slightly, but the analysis is sound. The spec reflects their understanding of the codebase. They don't need to rewrite it—they need to execute it.
This is what happens when the spec writer has context.
The Difference Between ChatGPT Specs and Agent-Written Specs
Let's name the elephant in the room: you could throw this bug report at ChatGPT right now, and it would produce something that looks professional.
It would suggest query optimization. It would mention caching strategies. It might even propose a microservices approach (because ChatGPT loves microservices).
And it would be useless to your engineers, because it's written about a generic product, not your product.
ChatGPT doesn't know:
- Which files your bug is actually in
- What your database schema looks like
- What technology you use for caching
- What your architecture constraints are
- Which solutions you've tried before and abandoned
- What your actual performance baselines are
ChatGPT writes specs like a consultant who's never seen your product. It's generic. It's safe. It covers the bases. And your engineers throw it away.
An agent-written spec is different because the agent has:
Indexed your codebase. It knows where things live, what patterns you use, and what constraints are baked into your architecture.
Analyzed your error logs. It knows which errors matter and which are noise.
Reviewed your analytics. It understands user impact at scale.
Traced your architecture. It knows which systems talk to each other and why.
Learned your patterns. It writes specs that sound like your team, reference your existing code, and propose solutions that fit your stack.
An agent spec is specific to your product. It's written in your language, for your codebase, with your constraints in mind. It's not aspirational—it's actionable.
That's the difference between "this looks right" and "we're building this tomorrow."
Use Cases for AI Spec Writing
AI spec writing isn't just for bug fixes. The pattern applies anywhere specs are currently written without full context.
Bug fix specs. A user reports that bulk actions fail silently on their account. An agent reads the bug report, traces it through error logs, identifies the actual failure point (an edge case in your permission system), checks if similar edge cases exist elsewhere, and writes a spec that fixes the root cause—not just this one case.
Feature specs. A product manager wants to add "save to favorites" functionality. An agent analyzes your codebase to see if favorites already exist in another context (they do, in your admin tool). It proposes reusing that infrastructure rather than building new. It identifies the database schema changes needed. It flags that notification service integration would require coordination with the backend team. The spec anticipates the friction before engineering hits it.
Incident postmortems. After an outage, your team needs to understand what happened and how to prevent it. An agent reviews logs, identifies the failure sequence, traces what monitoring missed, and drafts a postmortem spec that includes not just "what happened" but "what context would have caught this sooner."
Migration plans. Moving from one database to another. Refactoring a core service. Deprecating an old payment processor. These are context-heavy projects where the current state of the codebase, data volume, integration points, and dependencies matter enormously. An agent writes a migration spec that's grounded in what actually exists, not what you hope exists.
API design specs. Need to redesign your API? An agent analyzes current API usage (through logs), identifies which endpoints are load-bearing vs. legacy, and drafts a spec that maintains backward compatibility where it matters and deprecates fearlessly where it doesn't.
Performance improvement specs. When you notice slow load times, database queries, or API responses, an agent pinpoints the bottleneck, validates it with actual metrics, checks if similar patterns exist elsewhere that could be refactored together, and proposes an improvement spec that targets the root cause.
The pattern is the same across all of these: specs written with context are specs that stick.
How to Implement AI Spec Writing in Your Workflow
You're probably thinking: "This sounds great, but how do I actually add this to what we're already doing?"
Start small. You don't need to rewrite your entire spec process.
Pick one pain point. Where do your specs get rewritten most often? Is it bug reports? Is it feature specs? Is it incident response? Start there.
Index your codebase. This is the hard part and the essential part. Your agent needs to be able to search your code, understand your architecture, and reference patterns. If you're using Glue, this happens automatically. If you're using a general-purpose AI tool, you need to give it structured access to your repository.
Create a spec template for your agent. Your agent should write specs in the format your team already uses. If you use Confluence, specify that. If you use a certain YAML structure, provide examples. The less translation work required, the faster this integrates into your workflow.
Start with low-stakes specs. Bug reports are good first targets. They're smaller in scope than features. The impact of a "good enough" spec is contained. You can validate that agent-written specs are actually more useful before rolling this out to your quarterly planning process.
Measure the time saved. Track how long specs currently take to write and how often they get rewritten. Once you have baselines, measuring the impact of agent-written specs becomes straightforward. Most teams find that specs written with codebase context reduce engineering rewrite time by 60–80%.
Integrate with your existing tools. This should work with your current workflow, not replace it. Your PM tools, version control, error logging, and analytics platforms should feed into the spec writing process—not require you to learn new tools.
Iterate on context. Your agent will get better at writing useful specs the more you feed it signal about what specs your team actually uses. If a spec is adopted as-written, that's signal. If a spec gets heavily edited, that's signal too. Use both to improve.
The implementation is pragmatic. You're not replacing your PM process. You're automating the context gathering part of it—the part that currently happens in your engineers' heads.
FAQ
Q: Will this replace product managers?
No. PMs define what to build and why. They make tradeoff decisions. They prioritize. They talk to customers. AI spec writing automates the "write a technically coherent plan for building this" part—which is maybe 30% of PM work, and the part PMs spend time on that engineers have to redo anyway.
The PMs who thrive with AI spec writing are the ones who focus on strategy, user understanding, and prioritization. The ones who will struggle are PMs who define themselves by their ability to write detailed specs from incomplete information. That's not a valuable skill anymore—and frankly, it was a solvable problem, not a core PM competency.
Q: What if the codebase changes frequently? Will specs go stale?
Specs will reflect the state of the codebase when they're written, so yes—codebases that change rapidly will have specs that need updating. This is true of human-written specs too. The difference is that agent-written specs stay accurate longer because they're grounded in actual code patterns, not assumptions about how things work. When an engineer reads an agent-written spec, they're reading something that reflects the codebase's current state, not a PM's best guess.
Q: Can this handle specs for products I haven't shipped yet?
Not as well. The value of AI spec writing comes from codebase context. If you're building from scratch, you don't have patterns to reference, and the agent can't reference error logs or analytics. That said, AI can still help with feature design by reasoning about architecture and constraints. It just won't have the "lock in with actual code patterns" effect that makes specs stick for mature products.
Q: What if the spec is wrong? Won't engineers just rewrite it?
Sometimes. If the agent misunderstands the codebase, or analytics tell a different story than you expected, or there's an edge case nobody accounted for, engineering will still need to update the spec. That's normal. The difference is that agent-written specs are rarely wrong about facts. They're wrong about interpretation sometimes. They might overestimate the ease of a solution or miss a business constraint. But the technical analysis—which files change, what constraints exist, what patterns apply—is usually accurate. Human-written specs are wrong about facts regularly because facts about the codebase aren't available to the person writing.
The Bottom Line
Your engineers don't rewrite specs because your writing is bad. They rewrite them because specs written without codebase context miss critical information. You're solving for user intent and business impact. They're solving for technical reality. If the spec doesn't account for technical reality, it gets rewritten.
AI agents with codebase context can write specs that account for both.
This doesn't make PMs obsolete. It makes them more valuable, because they stop spending time on technical research and translation work. It's the same shift that happened when email automation tools took over scheduling—the person gets better at the strategic part of their job.
For teams shipping products at scale, AI spec writing is the leverage play. It's not about writing more specs. It's about writing specs that stick—that engineering can build from without translation.
That 40% of PM time you're losing to spec rewrites? You can have it back. And the specs your team produces will be ones your engineers actually respect.
Related Reading
- AI Ticket Triage: How Agents Classify, Route, and Prioritize
- AI for Product Managers: How Agentic AI Is Transforming Product Management
- Will AI Replace Project Managers? The Nuanced Truth
- AI Product Discovery: Why What You Build Next Should Not Be a Guess
- The Product Manager's Guide to Understanding Your Codebase
- Product OS: Why Every Engineering Team Needs an Operating System