The First Two Weeks
How AI turns practice gaps into structural debt.
The First Two Weeks
How AI Turns Practice Gaps into Structural Debt
At Initial Capacity, we believe that the first two weeks of a codebase may just be the most important code you’ll write. And getting them right has always been hard. Before agents, the process of writing code helped developers to comprehend the system. When teams start building with coding agents, that comprehension might not develop. Foundational decisions happen faster than understanding has a chance to form, and the debt that results can become structural before anyone realizes it is accumulating.
Three kinds of debt
Ward Cunningham introduced the debt metaphor in 1992¹ to describe a conscious tradeoff in software development: ship now, clean up later. The metaphor works whether the debt is intentional or not. Margaret-Anne Storey recently extended this concept in From Technical Debt to Cognitive and Intent Debt: Rethinking Software Health in the Age of AI to propose a triple debt model for reasoning about software health in the age of AI.
Storey's model identifies the following interacting debt types:
- Technical debt lives in the software: architecture, code quality, optionality.
- Cognitive debt lives in people: mental models, understanding, trust.
- Intent debt lives in externalized knowledge: goals, constraints, specifications, decisions.
These debt types are interdependent. Code nobody understands, built without captured rationale, becomes code nobody can safely change. The debts emerge from the initial conditions a team establishes early and compound across all three dimensions simultaneously. And we believe AI tools can accelerate all three.
Storey opens her paper with a student development team that hit a wall in week eight of a project. Simple changes were breaking things, but the primary problem wasn't messy code. The team had lost the shared understanding of what they'd built and why. Cognitive and intent debt had outpaced technical debt, and each made the others harder to address.
When AI accelerates debt accumulation, several things happen. Code gets generated faster than teams can understand it. Rationale never gets captured because the machine "just works". Architecture can begin to emerge from implementation order rather than deliberate design.
Sources of debt
Debt accumulates for plenty of reasons: time pressure, turnover, deliberate tradeoffs. Those sources are well understood. The specific debt mechanism that AI-assisted development introduces is relatively poorly understood.
One useful way to study that mechanism is through the gulfs between human intent and system behavior. Norman’s cognitive engineering work² describes interaction as a problem of alignment: users form intentions, act through a system, and then must interpret whether the system’s behavior matched what they meant. Shankar et al.³ apply this kind of analysis to LLM-based semantic data processing in DocWrangler. Their case is not AI-generated code, but it gives a bounded example of an LLM in practice, where teams must make nondeterministic behavior understandable, steerable, and reliable enough to use.
In that setting, Shankar et al. identify three specific gulfs:
- The Gulf of Comprehension: you don't understand your data, traces, or failure modes.
- The Gulf of Specification: your intent is vague and you haven't encoded what "good" means.
- The Gulf of Generalization: your system works in demos but not in the wild.
Gulfs as debt-formation mechanisms:
These gulfs become especially useful when the unit of analysis expands from a single LLM-enabled application to AI-augmented software delivery more broadly. In the single-application case, the gulfs describe gaps that make an LLM system hard to understand, steer, or trust. In the repeated-delivery case, those same gaps recur across prompts, generated code, tests, reviews, architectural decisions, and production behavior.
Fail to bridge a gulf, and the corresponding debt tends to follow. Comprehension failures produce cognitive debt. Specification failures produce intent debt. Generalization failures produce technical debt. The gulfs are the mechanism through which those debts form.
AI widens the gulfs
Fred Brooks drew a distinction in 1986⁴ between essential complexity, the hard problems inherent to a domain, and accidental complexity, the mess we create with our own tooling and process. AI compresses accidental complexity dramatically: the typing, the boilerplate, the mechanical translation of intent into syntax. But the gulfs sit on the essential side of Brooks’s line. Bridging them requires judgment that code generation does not supply by itself. Agents can let teams move forward before that judgment has happened. That is how the gulfs widen.
That widening shows up in specific ways. Comprehension gets harder when agents generate code nobody reads and make decisions in traces nobody inspects. Specification gets harder when simple prompts replace actual specification work, and ambiguity is resolved silently by the model rather than explicitly by the team. Generalization becomes harder when agents scaffold happy-path code that appears complete but isn't robust.
When unbridged, the gulfs reinforce each other. As cognitive debt grows, teams become less able to detect that they've fallen into the gulfs at all. Understanding of the codebase erodes, which makes it harder to recognize that specifications are vague, which makes it harder to catch generalization failures. The cycle feeds itself.
The trust problem
Cognitive debt has a specific failure mode: teams begin trusting outputs they do not understand. The tests pass, but the team no longer understands the codebase well enough to recognize when something is wrong.
Teams often use multi-agent architectures to improve generated code, but these systems can create a false sense of security rather than eliminate cognitive debt. The failure modes vary by architecture, but the underlying gulf remains the same.⁵
When understanding of the codebase wanes, there can be an instinct to add more human review to the development process. But reviewers face the same context gap as everyone else: they are trying to keep pace with generated code they did not build themselves. They lack the tacit codebase knowledge that usually comes from making changes directly. The mitigations therefore have to be structural, encoding intent into the development system itself so quality can keep up with the pace of development at scale.
Shankar et al. address the three gulfs with human-in-the-loop tools: in-situ notes for comprehension, prompt refinement for specification, and operation decomposition for generalization. In DocWrangler, those interventions support one bounded LLM workflow. Agentic coding operates at a different scale. The structural versions of those same mitigations move the work into the code generation pipeline itself and can include LLM-as-judge evaluators for comprehension, enforceable specs for specification, and agentic red teaming for generalization.
Moving human judgment up the stack is more effective than preserving human review at scale: setting intent, defining constraints, writing the criteria agents enforce. That work has to happen before the debt accumulates. Once cognitive debt sets in, the team loses the clarity to do it. They can't specify what good looks like because they no longer understand the system. The gulfs widen, the debt compounds, and each makes the other harder to see.
The process is reflexive—the gulfs produce debt that hides the gulfs that produced it.
Getting the foundation right
A team must break the reflexive cycle before it starts. No delivery methodology closes the gulfs by itself, and no orchestration pattern is a substitute for understanding the problem deeply enough to see them before they open. The countermeasure is a team with enough expertise to comprehend the problem, specify intent, and design for generalization before the first line of code is written.
With agentic coding, the first two weeks are when the work to understand has to happen. The cognitive debt that accumulates during the early days of a codebase becomes structural. It lives both in the code and the assumptions the code was built on. And by the time it's visible, the reflexive cycle is already running.
Before the cycle starts
The gaps in how we build with AI become the debts we carry in what we build. The two frameworks we've explored come from different communities, but together they point to the same conclusion: the practice gaps come first, and the debt follows. Teams that recognize this can act on it. Teams that don't will spend the next year paying down debt that they never meant to take on.
In practice, that means making intent concrete before scaling development is critical. This can be done by defining what success and failure look like, recording key architectural decisions and constraints, setting the criteria the codebase must satisfy, and testing beyond the happy path before scaffolding hardens into architecture.
The first two weeks still matter most. With coding agents, the debt is difficult to recognize at first but can cause large problems later. By the time you recognize it, you might be past the point of no return.
References
1: Cunningham, W. 1992. The WyCash Portfolio Management System. OOPSLA '92 Addendum to the Proceedings.
2: Cognitive Engineering chapter: Norman, D.A. 1986. Cognitive Engineering. In D.A. Norman & S.W. Draper (Eds.), User Centered System Design. Lawrence Erlbaum Associates.
3: Shankar, S., Chopra, B., et al. 2025. Steering Semantic Data Processing With DocWrangler. UIST 2025.
4: Brooks, F.P. 1986. "No Silver Bullet: Essence and Accidents of Software Engineering." Proceedings of the IFIP Tenth World Computing Conference.
5: We examined the architectural tradeoffs across these approaches in The Eventual Clone Wars, Initial Capacity, March 2026.