Picture this: a product manager and a lead engineer sit down to hash out a new feature. Because their team practices spec-driven development, they record the conversation and use the transcript to generate a baseline specification locally. Together, they refine the details and park the spec as a markdown file in the repository. As the feature takes shape, they’ll need to pull in context from architecture, security, and UX before it is ready to pass to an agent. In an ideal world, these external disciplines would enrich the specification directly—or the agents would simply pull the required standards from a shared knowledge base, saving everyone the manual legwork.
This setup sounds perfectly reasonable. But as these workflows become ingrained in everyday routines, teams need to step back and ask: is this process actually delivering value? When a specification is generated, how much time is invested in creating it versus writing code? Of that generation time, how much is spent on core content compared to hunting down the right context or reviewing drafts? And how much effort is pure toil—shuffling documents into position, manually purging outdated specs, or chasing down contradictions?
The Collaboration Gap
This process works, and it’s delivering real value. But dig beneath the surface and you’ll find that the tooling underneath still lacks a true collaborative foundation.
Most AI tools today focus on accelerating individual performance. Even co-work tools remain fundamentally document-driven—they can read and write across multiple files, but the unit of work is still the document itself. Having these tools available doesn’t guarantee that teams will change how they work together either. People are naturally reluctant to abandon processes that already function, prioritizing low-friction routines over abstract ideas of agility. Even teams doing frontier work—those who deeply care about optimizing their workflows—find that current AI tools struggle to provide a consistent, high-quality conveyor belt of context for downstream tasks.
This is the “context engineering” tax that most teams are paying whether they realize it or not. Creating, editing, formatting, and moving the documents needed to ground an AI task still involves manual steps. The higher the quality of context you want—curated, reviewed, and task-specific—the more steps it takes to produce it.
The Scoping Trap
In spec-driven development at its simplest, you ask an agent to generate a PRD, then break it down into implementation tasks. Teams who follow this process often report mixed results. If you dig into why an agent succeeds in one instance and fails in another, it almost always comes down to scope. A PRD focused on a single new feature across the stack—UI, API, and database—will likely succeed. A PRD trying to describe an entire subsystem with multiple endpoints will fail, forcing the agent to hallucinate or over-reason to fill in the blanks.
When teams realize that broad scoping is the root issue, they create additional processes to compensate. They draft a PRD, review it, refine it, and perhaps use an experienced human or an AI “judge” to classify the task size. They iterate until the PRD is high-quality, which often means breaking the context down into multiple smaller documents to enable progressive disclosure during development.
But this introduces a logistical nightmare: where do all these documents live? In the repo? A shared folder? Jira tickets? Moving these files and generating tickets adds toil. And when someone flags that an agent has picked up a contradiction or missing information, what then? Do they start over, hunting for the right document in a sea of constantly increasing PRDs?
The Collation Bottleneck
Usually, this collation effort falls on one or two individuals who have to gather scattered context and manually move it into position. Product decisions live in chat threads. Architecture rationale hides in ADRs. Design intent sits in Figma comments. Engineering context is buried in PR descriptions.
Engineers end up spending valuable time stitching these disparate artifacts into a coherent context file, hoping the output is high-fidelity enough to prevent downstream drift from ruining the process. Even with AI assistance, generating highly relevant context remains disjointed—you still need to know exactly where to find the upstream sources, and there are no built-in guarantees against drift.
Context Drift
Even if you solve the collation problem, a new one emerges.
Imagine you’ve successfully built a centralized context repository. It’s a massive win: all project knowledge lives in one spot, saving engineers from hunting down information across different silos. The workflow seems seamless—engineers draft an execution plan, pass it to an AI agent, and implementation begins.
But then you hit a critical edge case. Mid-implementation, an architect updates the referenced architecture design to prepare for an upcoming feature. Because the agent pulls from this live, unified space, it instantly consumes the new changes. This creates an immediate mismatch with the active plan. The agent either implements the wrong thing entirely or gets trapped in an endless reasoning loop trying to figure out why the architecture suddenly contradicts its original marching orders.
Enterprise Agile in the AI Era
Context drift isn’t just a technical problem—it exposes a deeper mismatch between how we organize work and how agents consume it.
In a traditional enterprise environment, the software development lifecycle relies heavily on implicit knowledge. A product manager writes a requirement, an engineer builds it, and Agile ceremonies bridge the gaps. Tickets typically contain just enough information for a human developer to reason through the problem or track down the right person for clarification. When requirements change, those same ceremonies ensure the new information is disseminated and the work is rescheduled.
But how does this fluid, human-centric model fit into an AI-native world? If an autonomous agent is halfway through an implementation when a requirement shifts, traditional Agile methodologies don’t have a clear answer. Do you let the agent finish its current run and create a new plan to refactor, or do you interrupt it to update the current plan?
A human engineer might start a task, realize the new requirements are a problem, and raise a blocker. An agent, however, will happily take the new information and “successfully fail” to implement the task at hand. This is the fundamental tension: Agile was designed around human adaptability—the ability to ask questions, read the room, and course-correct on the fly. Agentic workflows don’t have that luxury. Without explicit, structured context flowing between disciplines in real time, agents are left operating on potentially stale or contradictory information. Adding more ceremonies to compensate only treats the symptom. The process itself needs to be rethought.
Context Fidelity
Rethinking the process starts with acknowledging that even when the right context is available, meaning can still be lost in translation.
When using context to guide an implementation plan, we need to ensure the agent’s output hasn’t drifted from the original intent. We measure this alignment through fidelity—the degree to which downstream artifacts preserve the meaning of their upstream sources. In any interaction—whether human-to-human, human-to-agent, or agent-to-agent—there is always a risk of misinterpretation. Often, the breakdown starts with abstraction. When asking an agent to implement a task, did you use abstract terminology? The person with a clear mental map of how all the concepts relate often forgets that abstract terms can have multiple meanings depending on the context. Instead of being explicit, we end up assuming—or simply hoping—that the agent will automatically infer exactly what we meant. The inherent advantage of human-to-human interaction is that even if one person initially misses this bigger picture, they will usually grasp it eventually and bank that contextual knowledge for future use. Agents don’t build that intuition over time—every interaction starts from zero.
Consider a concrete example: a product manager writes “the system should support multi-tenancy.” To a security architect, that implies strict data isolation. To a database engineer, it might mean schema-per-tenant or row-level filtering. To a frontend developer, it could mean tenant-aware routing. A human team would hash out these distinctions over a few conversations. An agent, handed the abstract requirement without explicit disambiguation, will pick one interpretation and run with it—often the wrong one (stronger models might consider more than one).
Thought Traffic
The fidelity problem is compounded by speed. AI can generate ideas and artifacts faster than humans can govern them. Some engineers struggle to keep up and find it easier to accept what the AI has generated and deal with the fallout as it comes. But responsibility still lies with those who implement the code—auditors don’t care if agents made bad decisions. Engineers should not accept what the AI produces just for the sake of keeping up.
Part of the problem is that AI excels at generating large, comprehensive documents, which then forces developers to review them in their entirety. This creates a paradox: the tool that was supposed to save time now demands more of it. If you have all the information readily available and directly accessible by the agent, are those intermediate documents still needed?
Timely Context
Finally, even well-structured, high-fidelity context has a shelf life.
When downstream systems operate on stale or incomplete context, the effect is the same as context drift—except the cause isn’t a concurrent edit, it’s simple neglect. Architects update design documents, but if engineers never refresh their local references, the agent will wander in its reasoning—confidently building on outdated assumptions.
This is particularly insidious because staleness is invisible. Unlike a merge conflict that announces itself, outdated context looks identical to current context. There’s no built-in signal that tells an agent—or a human—“this information has been superseded.” Knowing when to use newer documentation is just as important as knowing when not to use it, and without an explicit mechanism for surfacing freshness, teams are flying blind.
The Current State of the SDLC
With these friction points in mind, here is a snapshot of what the SDLC currently looks like for teams trying to get the most out of AI agents. Keep in mind that the diagram below is a simplified overview. It doesn’t capture every single role or process, but rather highlights the core challenges we’re discussing today.
While friction exists across the entire lifecycle, this post zeroes in on three key phases: Planning and Spec Generation, Context Engineering, and Implementation. (We’ll tackle the remaining steps in future articles.)
Lately, I’ve become hyper-focused on how we generate and manage context during development. Drawing from our hands-on experience building out agentic SDLCs—and recognizing a real gap in the tools and skills available to support this work—we’ve set out to rethink Spec-Driven Development. Our ultimate goal is to figure out exactly what it takes to enable seamless, human-agent-human collaboration.
What’s Wrong with Using Documents?
Before jumping to the solution, it’s worth asking: why not just fix the documents? If the root problem is scattered, stale, and ambiguous context, why not build a better document management system?
The answer lies in the nature of documents themselves. Documents are monolithic—they bundle multiple ideas, decisions, and constraints into a single artifact. This bundling is what makes them useful for humans (you can read one document and get the full picture), but it’s also what makes them fragile for agents. When a single document contains dozens of interrelated concepts, an agent has to parse the entire thing, reason about which parts are relevant, and hope it doesn’t miss a subtle dependency buried in paragraph twelve.
More critically, documents don’t express relationships. A PRD might reference an architectural constraint, but the connection between the two lives entirely in the reader’s head. If the constraint changes, nothing in the PRD signals that it’s been affected. Multiply this across dozens of documents and you get the exact problems we outlined above: collation bottlenecks, context drift, and fidelity loss.
The idea is to move away from documents and start leveraging knowledge graphs.
A knowledge graph inverts this model. Instead of storing meaning in documents, it stores meaning in the relationships between discrete, well-defined concepts. Each concept is small enough to validate independently, and every relationship is explicit and traversable. This structure directly addresses the problems we’ve identified—and the following sections explain how.
A New Collaborative Framework
From Monolithic Documents to Atomic Concepts
The first shift is rethinking the unit of context. Instead of generating and maintaining large specifications, the knowledge graph decomposes ideas into atomic concepts—short, self-contained statements that each capture a single truth. “The API must support pagination” is an atomic concept. “The system architecture overview” is not.
You can build this graph conversationally. An assistant agent decomposes a discussion into atomic concepts as ideas are introduced. Each concept is individually reviewable, and as concepts are linked together, they build up into a nuanced, navigable understanding of the idea as it evolves. A human can then come in, ask questions or challenge assumptions, and the agent can use the graph to provide contextually relevant information or generate new concepts based on what already exists.
This directly addresses the scoping trap. Instead of debating whether a PRD is “too big” and manually breaking it into smaller documents, the graph handles granularity inherently. When an agent needs context for a task, it doesn’t ingest a monolithic document and hope for the best—it queries the graph for exactly the concepts relevant to that task, following relationship edges to pull in adjacent context as needed. The scope of what the agent sees is always proportional to the scope of what it’s doing, without any manual document splitting.
Grounding Concepts with Artifacts
Atomic concepts capture ideas in their purest form—precise statements and the relationships between them. But ideas alone aren’t always enough. A requirement like “the dashboard must render within 200ms” is clear as a concept, but the engineer implementing it also needs the performance benchmark script, the reference wireframe, and perhaps the SQL query that defines the dataset. These supporting materials aren’t ideas themselves—they’re the concrete assets that make ideas actionable.
This is where artifacts come in. Artifacts are standalone files—code examples, SQL queries, diagrams, design mockups—that act as supplementary context for concepts. They live outside the graph itself, stored separately and referenced by the concept nodes they support. When an agent queries the graph for a concept, it can follow these references to retrieve the relevant artifacts alongside it—no hunting through shared drives or Figma links.
This distinction matters. Concepts are the graph’s unit of reasoning: they can be linked, branched, reviewed, and merged. Artifacts are the graph’s unit of evidence: they ground abstract ideas in tangible, implementable assets. By keeping them separate but explicitly connected, the graph avoids the monolithic document problem while still giving agents—and humans—the full picture when they need it.
Preserving Fidelity Through Structure
The knowledge graph also tackles fidelity loss at a structural level. Remember the “multi-tenancy” example: a single abstract term that means different things to different disciplines. In a document, that ambiguity is invisible—it reads the same to everyone, and the divergent interpretations only surface downstream when implementations conflict.
In the graph, abstract concepts are explicitly decomposed into their discipline-specific meanings. “Support multi-tenancy” becomes a parent concept linked to “implement row-level data isolation” (security), “add tenant-aware API routing” (backend), and “build tenant switching in the navigation” (frontend). Each of these child concepts is precise enough to act on without ambiguity, and the explicit links make it impossible to address one without seeing the others.
This structural explicitness is what preserves fidelity across handoffs. When an agent picks up a concept for implementation, it isn’t interpreting an abstract paragraph—it’s reading a precise statement with explicit relationships to its upstream rationale and sibling requirements. The meaning doesn’t degrade because it was never compressed into ambiguous prose in the first place.
Isolating Work in Progress
On its own, this knowledge graph can still run into some of the issues we mentioned earlier, like context drift or exposing agents to incomplete information. To keep work isolated and prevent the main graph from getting cluttered by noisy, draft-stage concepts, we allow users to create separate branches. This way, if someone is developing a new feature, they have a safe staging ground to resolve contradictions and shape new ideas. The rest of the team can continue querying the stable mainline graph (the shared, canonical version) without any interruptions, and humans are spared the review fatigue of monitoring every intermediate update.
Branching also solves the timely context problem. When an agent begins work on a branch, it effectively snapshots the current state of the graph. If an architect updates a constraint on the mainline while the agent is mid-implementation, the branch remains stable—the agent won’t be derailed by changes it wasn’t designed to account for. When the branch is ready for review, the merge process surfaces any conflicts between the branch and the updated mainline, forcing an explicit resolution rather than letting the mismatch silently propagate.
Review-Based Branch Merging and Conflict Detection
Of course, isolating work in a branch is only half the battle; ensuring that new context meets the team’s standards before it hits the mainline is equally important. Rather than dumping raw, unchecked concepts into the primary graph, newly generated context must pass through a strict promotion lifecycle: it begins as a draft, undergoes review, and is only merged once approved.
This review process can be handled by a human expert, an autonomous agent acting as a judge, or a combination of both. When agents take on this role, they leverage the existing knowledge graph to deeply understand how concepts relate, automatically flagging potential contradictions or missing dependencies. If a new draft concept clashes with an established truth, the reviewer—human or AI—must resolve the conflict. This might mean refining the new idea, updating the outdated mainline concept, or rejecting the draft outright. By gating context creation this way, teams can guarantee that the shared knowledge graph remains highly curated and exceptionally reliable.
Cross-Discipline Visibility
The collation bottleneck we described earlier doesn’t just affect individual engineers—it affects entire disciplines. Product decisions live in one silo, architecture rationale in another, and design intent in a third. When an architect updates a technical constraint, the product manager who wrote the requirement it affects may never see the connection. When a designer adjusts a UI pattern, the engineer implementing it may not realize the change was driven by a usability finding that also impacts another team’s API contract.
The knowledge graph makes these cross-discipline relationships explicit and navigable. Because individual concepts and their relationships are tagged by discipline, an architect can trace how their technical decision connects to the product requirement it constrains. A designer can see how their pattern relates to an engineering limitation. A product manager can explore how a single requirement ripples across architecture, design, and implementation. Instead of relying on sync meetings or hoping that someone manually stitches together the cross-functional picture, the graph surfaces these connections on demand—giving every discipline a clear line of sight into how their work shapes and is shaped by the others.
This also addresses the Enterprise Agile question we raised earlier. Agile ceremonies exist largely because documents and tickets don’t carry enough context on their own—humans need to supplement them with conversation and coordination. When the graph makes cross-discipline dependencies explicit and relationships traversable, much of the context that would otherwise require a sync meeting is already visible. Ceremonies don’t disappear, but their purpose shifts from disseminating information to making decisions—which is what they should have been for all along.
Tracing Provenance
Context drift and fidelity loss are difficult to diagnose without a clear record of how ideas evolved. If an implementation diverges from its original intent, was it because the requirement changed, the architecture shifted, or the agent simply misinterpreted the context? Without provenance, these questions become archaeological expeditions.
The knowledge graph maintains a strict audit trail: what decisions were made, by whom, when, and why. More importantly, it preserves a direct line of sight from code implementation back to the originating concepts. This traceability serves multiple purposes—auditors get the compliance trail they need, new engineers can understand why something was built a certain way rather than just how, and when a bug surfaces, the team can trace it back to the original concept to determine whether the intent was wrong or the implementation drifted.
Governance and Feedback
The thought traffic problem we raised earlier—where AI generates ideas and artifacts faster than humans can govern them—creates a real governance challenge. If external systems, particularly AI agents, can freely modify the knowledge graph, the carefully curated context that the branch and review process protects would quickly erode. At the same time, shutting out external contributions entirely would waste the very capabilities that make AI valuable.
A suggestions mechanism solves this by providing a queue-based channel for external systems to propose changes without bypassing human governance. An AI agent monitoring a codebase might detect that an implementation has diverged from a documented requirement, or a CI/CD pipeline might flag a new dependency that contradicts an architectural constraint. Rather than modifying the graph directly, these systems submit suggestions that enter a structured lifecycle: they arrive as pending proposals, are reviewed by a human stakeholder, and are either accepted—at which point they are routed through the standard branch and merge pipeline—or rejected outright.
On the review side, verification signals serve as the feedback mechanism that bridges automated evaluation and human decision-making. When a branch or suggestion is submitted for review, agents, tools, and human reviewers generate evaluation reports that are captured as signals logged directly against the branch. These signals are deliberately sourced from a broad set of submitters—not just registered stakeholders, but also CI/CD pipelines, automated test suites, and external reviewers—and are routed immediately to the relevant decision-makers. Critically, verification signals do not make the final call. They provide the context that empowers the humans who do, ensuring that the speed of automated evaluation never outpaces the rigour of human judgement.
Looking Ahead
This post has laid out both the friction points in today’s AI-assisted SDLC and a framework for addressing them. The core thesis is straightforward: if we want agents to collaborate effectively across disciplines, we need to move beyond documents as the unit of context. A knowledge graph built on atomic, linked concepts—governed by branching, structured review, and human-in-the-loop feedback—gives teams a foundation for high-fidelity, drift-resistant collaboration.
In future articles we’ll dive deeper into generating the graph using converstional agents and evaluating whether these concepts improve our agentic workflows.
If you’re navigating similar challenges in your own team’s agentic workflows, I’d love to hear what’s working and what isn’t. The problems outlined here are shared across the industry, and the solutions will be too.