Posts

The Context Engineering Ladder: Is plan.md a Bottleneck for Agentic Scaling?


# Why Spec-Driven Development Isn't Enough

> **Spec-driven development** is the practice of giving AI coding agents structured requirements (PRDs, tech specs, user stories) to generate code — an improvement over raw prompting, but fundamentally limited because specs encode *what* to build without the *why*. Specs are snapshots stripped of reasoning: they don't carry validated assumptions, persona feedback, risk analysis, or strategic context. The result is "perfectly executed bad ideas" — agents that build exactly what the spec says, even when the spec is wrong.

The pitch is compelling: Write a spec, hand it to an AI coding agent, and watch working code materialize.

Tools like Devplan and Traycer have built entire products around this idea. They call it "spec-driven development"—structured requirements that guide AI agents to produce better, more consistent code.

**And they're half right.**

Specs do improve AI coding output. Structure beats chaos. Clear requirements beat vague prompts.

But there's a fundamental problem: **Specs tell agents *what* to build. They don't tell agents *why* they're building it.**

## The Spec Ceiling

Here's what happens in spec-driven development:

1. Human writes a spec (PRD, tech spec, user stories)
2. AI agent receives the spec
3. Agent generates code that matches the spec
4. Human reviews and iterates

This works great for well-understood problems. If you know exactly what you want, specs are efficient.

But most product decisions aren't well-understood. They're bets. And specs encode those bets without questioning them.

Consider a spec like:

> "Add a dashboard showing user activity metrics with daily/weekly/monthly views, export to CSV, and email scheduling."

A spec-driven agent will build exactly this. It might even build it well—clean code, good tests, proper error handling.

But the spec never asked:
- Do users actually want this dashboard?
- Is "activity metrics" the right data to show?
- Will anyone use email scheduling, or is that scope creep?
- What assumptions are we making about user behavior?

**The spec was precise. The spec was also wrong.**

## Specs Without Context Are Dangerous

The deeper problem: specs are snapshots. They capture requirements at a moment in time, stripped of the reasoning that produced them.

When an AI agent works from a spec, it knows:
- ✅ What features to build
- ✅ What acceptance criteria to meet
- ✅ What technical constraints to follow

But it doesn't know:
- ❌ Why this feature matters more than others
- ❌ Who the users are and what they actually need
- ❌ What assumptions haven't been validated
- ❌ What risks could make this feature worthless
- ❌ What the business is trying to achieve

This missing context leads to a specific failure mode: **perfectly executed bad ideas**.

The agent builds exactly what you asked for. You just asked for the wrong thing.

## From Specs to Product Context

The alternative isn't abandoning specs. It's expanding what we give AI agents.

**Product context** is everything an agent needs to make good decisions—not just execute instructions:

| Spec | Product Context |
|------|-----------------|
| What to build | Why we're building it |
| Feature requirements | User needs and pain points |
| Acceptance criteria | Success metrics |
| Technical constraints | Business constraints |
| Current task | Product strategy |
| This feature | The whole product |

When an AI agent has product context, it can:

1. **Question requirements** - "This spec says daily email reports, but the persona data shows users check dashboards twice a month. Should we reconsider?"

2. **Make tradeoffs** - "Given the budget constraint and validated priorities, I'll implement the core feature but flag the export function as a future enhancement."

3. **Avoid validated failures** - "The pre-mortem identified 'complex onboarding' as a high-risk assumption. This implementation adds 3 new steps—that conflicts with our risk mitigation strategy."

4. **Maintain coherence** - "The product voice is 'direct and slightly irreverent.' I'll adjust the error messages to match."

This isn't science fiction. It's what happens when product management artifacts flow into AI agents.

## The Context Flow

Here's how product context reaches AI agents in practice:

```
Product Research → Validation → Strategy → Planning → Execution
      ↓               ↓            ↓          ↓          ↓
   Personas      Pre-mortem    Priorities   Specs    AI Agent
   User needs    Risk analysis  Goals       Tasks    (has full context)
   Competitors   Assumptions    Roadmap     Stories
```

Each stage produces artifacts. Traditional tools treat these as separate documents—maybe in Notion, maybe in Confluence, maybe in someone's head.

**The breakthrough is organizing this into a queryable context graph.**

### The Product Context Graph

A context graph connects product artifacts—personas, risks, assumptions, decisions, features—into a navigable structure. Instead of isolated documents, you get relationships:

- This feature → serves this persona → addresses this pain point
- This risk → threatens this assumption → requires this experiment
- This decision → made because of this constraint → affects these features

When AI agents can traverse a context graph, they don't just retrieve information—they understand connections. "Why are we building this?" has an answer that links back through validated research.

Tools like [Model Context Protocol (MCP)](/docs/setup) enable this. Your AI coding environment can query the product context graph as it works:

- "What's the target persona for this feature?"
- "What risks were identified for this area?"
- "What's the pricing constraint?"
- "Has this assumption been validated?"

The agent isn't just following a spec. It's working with full product awareness.

## Why This Matters for AI-Assisted Development

As AI agents become more capable, the context we provide becomes more important.

A junior developer following a spec can only execute. A senior developer with full context can push back, suggest alternatives, and avoid mistakes.

**AI agents are the same way.**

Give them specs, and they execute specs. Give them product context, and they become collaborators who understand what they're building and why.

This is especially critical for:

### Complex Features
The more complex the feature, the more decisions get made during implementation. Without context, those micro-decisions drift from product intent.

### Long-Running Projects
Specs get stale. Product context includes the reasoning that updates as the product evolves.

### Multi-Agent Workflows
When multiple AI agents work on a codebase, shared product context keeps them aligned. Specs alone create fragmentation.

### Validation Integration
Product context includes what's been validated and what hasn't. Specs just encode assumptions as requirements.

## What Spec-Driven Tools Miss

The spec-driven development tools have built useful infrastructure:

- **Devplan**: Living projects, guided execution, task decomposition
- **Traycer**: PRDs, tech specs, agent handoff, verification

These are good features. But they're optimized for a different problem.

They assume you know what to build. They help you build it efficiently.

**Cutline assumes you might be wrong.** It helps you figure out if you should build it at all—and then carries that validated context into development.

| Spec-Driven Approach | Context-Driven Approach |
|---------------------|------------------------|
| Starts with requirements | Starts with validation |
| Specs → Agent → Code | Validation → Context Graph → Agent → Code |
| Isolated documents | Connected context graph |
| "Build this correctly" | "Build the right thing correctly" |
| Execution efficiency | Decision quality + execution |

## The Integration Path

If you're using spec-driven tools, you don't have to abandon them. You can augment them with product context.

### Step 1: Validate First
Before writing specs, run a [pre-mortem](/pre-mortem). Identify risks. Test assumptions. Talk to [AI personas](/ai-product-manager) that represent your users.

### Step 2: Capture Context
Don't just capture requirements—capture the reasoning. Why this feature? What user need does it serve? What happens if we're wrong?

### Step 3: Make Context Available
Use MCP or similar protocols to make product context queryable by your AI coding environment. When the agent is implementing a feature, it should be able to access:
- The validated user need
- The risk analysis
- The persona feedback
- The strategic priorities

### Step 4: Close the Loop
As implementation reveals new questions, feed them back into product validation. The context should evolve, not stay frozen.

## The Bigger Picture

Spec-driven development is a step forward from prompt-and-pray coding. Structure beats chaos.

But the next step is **context-driven development**—where AI agents understand not just what to build, but why it matters, who it's for, and what could go wrong.

This isn't about replacing specs. It's about embedding specs in the larger context that makes them meaningful.

**The goal isn't AI that builds faster. It's AI that builds smarter.**

And that requires more than specs. It requires the full picture of what you're building and why.

---

## FAQ

**Q: Why isn't spec-driven development enough?**

Specs tell agents what to build but not why. They encode bets without questioning them, don't include validated assumptions or risk analysis, and produce "perfectly executed bad ideas" when the spec is wrong.

**Q: What is context-driven development?**

The evolution beyond specs. Context-driven development gives agents validated assumptions, persona feedback, strategic constraints, and risk analysis — so they can question requirements, make tradeoffs, and maintain coherence.

**Q: What is a product context graph?**

A connected structure where nodes represent features, assumptions, personas, risks, and experiments, with edges showing relationships. AI agents traverse this to understand why they're building something, not just what to build.

---

*Cutline provides the product context layer for AI-assisted development. Validate ideas with [pre-mortem analysis](/pre-mortem), get feedback from [AI personas](/ai-product-manager), and connect your product context to AI coding agents via [MCP integration](/docs/setup).*
