The Intent Debt

Addy Osmani (addyosmani.com) · rss · 2026-06-06 Reader 🖥️

practical · mixed — Argumentative-with-prescriptions. Osmani imports a taxonomic model (Storey's triple debt) to do theoretical work — distinguishing intent debt from technical and cognitive debt — and then makes the case that agents alter the economics of one specific cell in that taxonomy. The closing section is operational: write specs for intent, treat AGENTS.md as an intent ledger, log decisions, run a self-improving learnings loop. Practical because every claim is ultimately in service of 'externalize the why'.

Structure

Key terms

• Intent debt Intent Debt
  The absence or erosion of the EXTERNALIZED rationale, goals and constraints that explain why the system is the way it is — recorded in artifacts (specs, AGENTS.md, ADRs, learnings files, commit messages) that a teammate, a future you, or an agent can actually read. Crucially distinct from understanding-in-your-head: intent that exists only inside the senior engineer's skull is enormous intent debt for everyone (and every agent) else.
• Technical debt (Osmani's framing within the triple model) Technical Debt
  Implementation choices that make the system harder to change later — tangled modules, leaked abstractions, deadline shortcuts. Lives in the code. Announces itself via slow builds, fragile tests, dread of touching a file. Increasingly cheap to take on AND increasingly cheap to pay down because an agent can refactor.
• Cognitive debt (Osmani's framing within the triple model) Cognitive Debt
  Erosion of shared understanding — the gap between how much code exists and how much any human actually understands. Lives in people. Accumulates when the system grows faster than the team's mental model of it. Recoverable in a way underrated: you can ask the agent to explain the code back to you. Osmani equates it with what he previously called comprehension debt.
• Independence (of the three debts)
  The technical/cognitive/intent debts are orthogonal axes: you can have pristine code AND nobody understands it AND no externalized rationale, in any combination. From the inside they 'feel similar' but 'are not the same bill'. The claim is operationally important — it means cleaning the code or rebuilding mental models will not reduce intent debt at all.
• Externalize (intent) Intent Debt
  Move rationale OUT of human heads and INTO machine-readable artifacts. The verb does the work of the whole prescription section. 'External' means readable by an agent, not just by a teammate.
• Tacit intent Intent Debt
  The why-of-the-system that humans absorb slowly through hallway conversations, code review comments, incident lore ('we don't do it that way because of an incident in 2023'), and senior-engineer mentorship. Worked for years because humans accumulated it; breaks under agents because agents do not.
• Cold start (of an agent session) Intent Debt
  Every agent session begins without the long-term memory humans build over years; whatever isn't in a readable artifact, the agent doesn't have. Multiplied by every agent you run, every session. The economic engine of the post.
• Plausible guess (about intent) Intent Debt
  What an agent produces when intent is missing from artifacts: a confident-sounding inference from the code that is structurally indistinguishable from real rationale, and worse than the agent admitting it doesn't know. Frames the failure mode as fabrication rather than absence.
• Load-bearing rationale Intent Debt
  The subset of why-decisions whose loss would be expensive to reconstruct or dangerous to get wrong. The triage criterion that resolves the 'you can't write down everything' objection: capture the load-bearing why, not the totality.
• AGENTS.md (as intent ledger, not config) Agent Context Files (CLAUDE.md / AGENTS.md)
  A file that describes what the TEAM means — conventions, 'we don't do it this way because…', constraints invisible in any single file — as opposed to /init-style auto-generated files that describe what the code IS. The distinction is what makes the artifact useful to agents.
• Decision log / lightweight ADR Architecture Decision Records
  Capture-at-the-moment-of-decision artifacts. Pure intent-debt paydown: trivial cost at write time, enormous cost to reconstruct eight months later after the decider has left.
• Self-improving agent / learnings file
  An agent loop that writes intent back into the repo at end of session — 'we tried X and it didn't work because Y' — converting each mistake's root cause from one person's bad-afternoon memory into a durable artifact. An 'intent-debt pump running in reverse'.
• Helplessness (as the felt experience of intent debt)
  Intent debt is not noticed as friction (the way technical debt is) — it is noticed as 'a particular kind of helplessness': defending a design choice you can't reconstruct, or accepting an agent's refactor because nobody can say if the guard clause was load-bearing. The operational test for detecting intent debt.
• Orchestration tax (as intent-debt tax) Orchestration Tax / Human Review Bottleneck
  Cross-reference to Osmani's previous post: the cognitive bandwidth cost of managing many agents is 'partly an intent-debt tax' — a lot of what makes orchestration exhausting is re-supplying the intent you never wrote down, once per agent per session.

Propositions

• explicitestablishedSoftware debt has three independent loci — code (technical), heads (cognitive), and artifacts (intent) — per Margaret-Anne Storey's Triple Debt Model.conf: high
  extends ←AI coding creates two kinds of debt. You're only measuring one · p1 — This is the primary-source interview with Storey, who coined the term in Oct 2025 and grounds it in Naur's programming-as-theory-building — the direct source Osmani's Triple Debt Model import was paraphrasing secondhand.
  supports ←Five studies that are changing how I think about AI in software engineering · p8 — This is the primary-source account of Storey's Triple Debt Model (code/heads/artifacts) that Osmani's post cites.
  supports ←From Technical Debt to Cognitive and Intent Debt: Rethinking Software Health in the Age of AI · p1 — This is the primary source Osmani's p1 paraphrases almost verbatim ('three independent loci -- code, heads, artifacts'); confirms Osmani's citation is faithful to Storey's own framing.
  supports ←How do software development teams manage technical debt? - An empirical study · p10 — This 2016 case study shows intent debt's core mechanism -- unexternalized rationale living only in a developer's head and "sometimes forgotten" -- predates AI agents entirely; it was already the primary failure mode of human-only TD documentation, which osmani-intent-debt's framework explains why agents make acutely worse (no tacit memory to fall back on).
• explicitcorroboratedIntent debt is the absence or erosion of EXTERNALIZED rationale, goals and constraints — not the absence of understanding, but the absence of understanding written down where an agent can read it.conf: high
  supports ←Five studies that are changing how I think about AI in software engineering · p9 — Storey's 'intent debt lives in artifacts — goals, constraints, and rationale unclear, unwritten, or forgotten' is a near-identical definition to intent debt as the absence/erosion of externalized rationale.
  extends ←Dropbox Integrates MCP and Dash to Close the Gap Between Security Design and Code Review · p2 — Osmani defines intent debt as the absence or erosion of externalized rationale 'where an agent can read it'; this document is a production case showing the erosion half specifically as a discoverability/connection failure — the rationale WAS externalized (a design doc exists) but decays into being effectively unreadable-by-agent once disconnected from the evolving codebase, motivating a retrieval-infrastructure fix rather than an authoring fix.
  extends ←Loop Engineering · p8 — Applies Osmani's own intent-debt framing (externalized rationale an agent can read) specifically to skills-as-a-loop-primitive: a skill is intent written down once so the loop doesn't re-derive project context from zero every cycle.
• explicitThe three debts are independent — pristine code, perfect personal understanding, and zero externalized rationale can all coexist.conf: high
• explicitFrom the inside the three debts 'feel similar' — they are not subjectively distinguishable, which is what lets intent debt accumulate undetected.conf: high
• explicitcontestedAgents can pay down technical debt (refactor a tangled module) and partially pay down cognitive debt (re-explain the code), but they cannot pay down intent debt.conf: high
  contradicts ←AI coding creates two kinds of debt. You're only measuring one · p10 — Storey (interviewed directly here, as the term's originator) states cognitive debt has no repayment mechanism — you cannot recover understanding never built or restore understanding a team never had. Osmani's piece claims agents can 'partially pay down cognitive debt' by re-explaining code. Direct tension between the primary source and Osmani's secondhand gloss (see gap g4).
• explicitdevelopedIntent is structurally the one input that has to come from a human — agents can only fabricate plausible-sounding intent from the code, not generate the actual intent.conf: high
  extends ←Agentic Code Review · p8 — Extends the intent-debt thesis (intent must originate with a human; agents can only fabricate plausible intent from the code) to the review task specifically — review has become the act of reconstructing an intent that never existed, which is why it is slower.
• explicitAn agent's fabricated 'guess at intent' is worse than the agent admitting it doesn't know, because confident plausibility is indistinguishable from real rationale at the point of merge.conf: high
• explicitcorroboratedAgents start most sessions cold and carry forward no tacit intent; whatever isn't externalized into a readable artifact, they simply don't have.conf: high
  supports ←Encoding Team Standards · p2 — Both diagnose the same root failure: agents (and, here, differently-experienced developers) carry forward no tacit intent unless it is externalized into a readable, structured artifact — this article proposes one concrete executable format for that externalization.
• explicitBringing agents onto a team is like doubling its size overnight with junior people who have no long-term memory.conf: high
• explicitUn-externalized intent used to be an occasional cost (onboarding, departures); with agents it is paid every session, multiplied by every agent.conf: high
• explicitThe orchestration tax — Osmani's previous diagnosis of agent-management exhaustion — is partly an intent-debt tax: re-supplying the unwritten why per session per agent.conf: high
• explicitYou cannot capture all intent in a spec; but the fact that you cannot capture all of it is not a license to capture none of it.conf: high
• explicitThe implicit decisions an agent now makes on your behalf are precisely the ones whose rationale evaporates if the load-bearing why isn't recorded, because nobody will be able to reconstruct them later.conf: high
• explicitcorroboratedCode is the answer; intent is the question the answer was supposed to be solving — and AI is brilliant at producing answers to questions you forgot to write down.conf: high
  supports ←Comprehension at AI Speed: Building a Context Store for Evolutionary Architecture · p1 — Both frame AI as separating the artifact (code) from the reasoning that produced it; this article names the general phenomenon 'the context gap' where Osmani names the specific unpaid debt 'intent debt.'
• explicitHigh intent debt is felt not as friction but as a 'particular kind of helplessness' — inability to defend or reconstruct a design choice.conf: high
• explicitTests that encode previous behavior but not intent will pass clean refactors that quietly change user-depended-on behavior.conf: high
• explicitSpecs should be written for INTENT (goals, constraints, non-negotiables, explicit definition of done) rather than for IMPLEMENTATION; specs detailed enough to BE the program are just the program in a slower language.conf: high
• explicitcorroboratedAGENTS.md should be treated as an intent ledger (conventions, 'we don't do it this way because…') not as auto-generated config describing what the code is.conf: high
  supports ←The AI-Native SDLC playbook · p4 — Claxton's intent.md — originator-written, human-corrected, committed to a shared versioned home — is a concrete team-level implementation of exactly what Osmani argues AGENTS.md should be used as: a reviewed intent ledger, not auto-generated config describing the code.
  extends ←Harness engineering: leveraging Codex in an agent-first world · p5 — Osmani argues AGENTS.md should be an intent ledger, not auto-generated config; this piece supplies the structural reason it must also stay short and point elsewhere — a monolithic file suffers context scarcity, non-guidance, rot, and unverifiability, so the ledger has to be a short map into a separately-enforced docs/ system of record, not the encyclopedia itself.
  extends ←Stop Using /init for AGENTS.md · p9 — Osmani's own later piece reframes AGENTS.md specifically as an 'intent ledger' of non-discoverable why; this article's 'Layer 1 protocol file... minimum essential facts the agent genuinely cannot discover' is the same move stated architecturally rather than philosophically.
• explicitRecording the WHY at the moment of decision is trivially cheap; reconstructing it eight months later, after the decider has moved, is enormous — and agents have made logging cheaper than ever.conf: high
• explicitSelf-improving agent loops that update a learnings file at end of session pump intent back into the repo automatically, converting bad-afternoon memories into durable artifacts.conf: high
• explicitFor decades the scarce, valuable thing was the ability to produce a correct implementation; AI has made code cheap and comprehension recoverable, leaving intent as the one input that still has to originate with a human and that humans are worst at externalizing.conf: high
• explicitdevelopedWrite down the why — it is becoming the most valuable thing you can leave in the repo.conf: high
  extends ←Agentic Skill Decay · p8 — Concretizes the same author's earlier 'write down the why' prescription into specific durable-capture mechanisms (lessons.md, lint rules, type constraints, tests) for lessons learned while working with an agent.
  refines ←AI Development Patterns · p8 — Osmani argues 'write down the why — it is becoming the most valuable thing you can leave in the repo'; Duvall's Knowledge Hoarding anti-pattern qualifies this with a selectivity ceiling — capture only high-impact (>80% success) patterns and costly failures — because indiscriminate externalization becomes a new, unmaintained debt of its own.
• explicitdevelopedThe recurring symptoms Osmani has named over recent months (comprehension debt, cognitive surrender, orchestration tax) are retroactively unified as instances of intent-debt management.conf: high
  refines ←Own the Outer Loop · p1 — Both propositions retroactively unify Osmani's recently-named recurring costs under one master concept, but they nest rather than agree: p23's unification names intent debt as the master concept covering comprehension debt, cognitive surrender, and orchestration tax; this essay unifies a different, overlapping triad (cognitive surrender, cognitive debt, orchestration tax) under accountability/outer-loop ownership instead, and drops intent debt from the named set entirely.
• implicitcontestedIntent debt is primarily an individual-developer (and possibly individual-team) problem to be solved by personal discipline around externalization.conf: high
  contradicts ←The AI-Native SDLC playbook · p12 — Osmani frames intent debt as 'primarily an individual-developer (and possibly individual-team) problem to be solved by personal discipline around externalization'; Claxton locates the same externalization need in organization-wide process infrastructure — a shared intent.md home a platform team stands up, a product-owner review gate, and governance enforced as code — not personal discipline.
  contradicts ←Dropbox Integrates MCP and Dash to Close the Gap Between Security Design and Code Review · p9 — Osmani's article addresses intent debt entirely as an individual-developer discipline problem (implicit, since all its prescriptions target the developer). Dropbox's Dash+MCP initiative is an org-level infrastructure response — built and operated by a platform team, not left to individual externalization habits — that treats the same problem as solvable through tooling and process at organizational scale, cutting against the 'primarily individual' framing.
  contradicts ←Linear’s CEO just described the biggest shift in product team... · p4 — Osmani frames intent debt as primarily an individual-developer (or individual-team) problem solved by personal discipline around externalization; this thread instead frames structured, systemic tooling (an organizational coordination layer) as the fix, implying intent capture can be designed-for at the system level rather than left to individual discipline.
• implicitestablishedAGENTS.md, ADRs, learnings files and specs are the right substrate for externalized intent — i.e., the right artifact format already exists.conf: high
  extends ←Comprehension at AI Speed: Building a Context Store for Evolutionary Architecture · p5 — Agrees specs/AGENTS.md/ADRs are the right substrate for externalized intent, and extends the claim by proposing they be unified into one versioned, queryable 'context store' fed by three integrated disciplines rather than maintained as separate artifacts.
  supports ←Encoding Team Standards · p2 — This article's categorized, repository-resident instructions are a specific instantiation of the substrate Osmani names (AGENTS.md, ADRs, learnings files, specs) for externalized intent — adding a concrete four-part anatomy to that general claim.
  supports ←Scaling the Practice of Architecture, Conversationally · p8 — Harmel-Law's ADR-as-thinking-checklist, with a mandatory recorded advice field, is an early, concrete answer to the later claim that ADRs (alongside AGENTS.md and specs) are the right substrate for externalized intent.
  refines ←When AI Writes the Code, Specifications Need an Exit Strategy · p5 — Agrees AGENTS.md/ADRs/specs are legitimate substrates for intent, but narrows their role to only the residual facts with no native-artifact home — most durable facts should move to schemas/types/tests/policies/telemetry instead of staying in prose.
• implicitDevelopers can reliably identify which decisions are 'load-bearing' at the moment of decision (before they know which ones will matter later).conf: high
• implicitThe right reader for externalized intent is a future agent (and secondarily a future teammate), not the current author — so artifacts should be optimized for machine-readability.conf: high
• implicitStorey's Triple Debt Model is the correct taxonomy of software-development debt for the agent era — not, e.g., process debt, dependency debt, data debt, or organizational debt.conf: high
• implicitcorroboratedTests can encode intent — they don't, but they could — implying a path Osmani hints at but does not develop: intent-specifying tests as a fourth paydown lever.conf: medium
  supports ←From Technical Debt to Cognitive and Intent Debt: Rethinking Software Health in the Age of AI · p10 — Osmani's p29 speculates 'tests can encode intent -- they don't, but they could' as an underdeveloped fourth paydown lever he hints at without developing. Storey's paper explicitly develops exactly this practice ('Executable intent': BDD specs/tests capturing purpose, distinct from tests that only encode prior behavior) -- the primary source already contains the lever Osmani's piece gestures at but leaves undeveloped.

Arguments

Narratives

• Margaret-Anne Storey's Triple Debt Model — technical, cognitive, intent — imported as the organizing taxonomy with a forward citation to arXiv 2603.22106.
  → Earns the framing through attribution to a researcher rather than asserting it as Osmani's own coinage. Lets the post stand as 'making a research model operationally legible' rather than 'inventing yet another debt type'.
• The senior engineer who'd been there four years — the human-as-intent-documentation. Expensive, lossy, but worked.
  → Names the strategy teams have used for decades to manage intent debt without externalizing it. Frames externalization as the response to a strategy that has just stopped working, not as a new virtue.
• Bringing agents onto a team is like doubling its size overnight with entirely junior people — and with no long-term memory.
  → The central analogy. Makes the cold-start economics intuitive by mapping them onto a familiar onboarding cost, then sharpening with the memory twist.
• Vignette 1: An agent 'fixes' a bug by removing a guard clause; nobody can say whether it was load-bearing or leftover, because the reason it existed was never recorded.
  → Operationalizes intent debt at the line level. Implicitly: code reviewers' inability to defend lines is the diagnostic.
• Vignette 2: A behavior users depend on quietly changes in a refactor; the review passed (clean diff, green tests) because tests encoded previous behavior, not intent.
  → Implicit argument for intent-specifying tests as a fourth lever — though Osmani does not develop it explicitly. Also names a class of agent failure that is invisible to current code-review tooling.
• Vignette 3: Two services talk over a queue instead of a direct call; the honest answer to 'why?' is 'an agent suggested it and it seemed fine'.
  → Names a specific class of intent debt — architectural decisions taken on agent recommendation without recorded justification. The 'with interest already accruing' phrasing converts a one-time choice into a compounding liability.
• Cross-reference to 'Cognitive Surrender' — defending a design choice you can't reconstruct.
  → Positions intent debt as the team-scale written-down version of the personal-posture failure mode he previously named. Implicitly retconns several earlier posts as symptoms of one underlying disease.
• Self-citation cluster: 'good spec', 'stop using /init' (AGENTS.md), 'automated decision logs' (ADRs), 'self-improving agents' (learnings files).
  → Retroactively unifies four prior posts as 'intent-debt management I didn't have the word for'. Establishes Osmani's series as a coherent program rather than a sequence of related observations.
• Closing reframe: 'Code is the answer. Intent is the question the answer was supposed to be solving, and AI is brilliant at producing answers to questions you forgot to write down.'
  → Elevates the personal-workflow point to an era-level claim. Most quotable line; designed to travel.

Questions addressed

• ✅ What is intent debt and how does it differ precisely from technical debt and cognitive debt?
  Intent debt is the absence/erosion of EXTERNALIZED rationale in artifacts. It is independent of code quality (technical) and of personal understanding (cognitive). The three are orthogonal; they 'feel similar from the inside but are not the same bill'. The defining feature is artifact-locus: rationale that exists only in human heads is high intent debt regardless of how well-understood the system is.
• ✅ Why can't AI agents pay down intent debt the way they can pay down technical (and partially cognitive) debt?
  Because intent is the one input that has to originate with a human — it is informational, not capability-limited. An agent can fabricate plausible-sounding intent from the code, but a fabrication is structurally worse than the agent admitting ignorance, because at merge time the two are indistinguishable. Stronger future models do not close this gap.
• ✅ Why is intent debt urgent now, when teams have managed it informally for decades?
  Agents start cold every session with no long-term memory; un-externalized intent used to be paid occasionally (onboarding, departures) and now is paid every session, per agent. The senior-engineer-as-intent-documentation strategy collapses when half the team is agents.
• ✅ How can the reader detect intent debt in their own system?
  By the felt experience of helplessness rather than friction. Three vignettes operationalize: inability to defend a guard clause's existence, behavior change that passes review because tests encoded behavior not intent, architectural choices justified only as 'an agent suggested it'. The diagnostic surface is code review against agent output.
• ✅ How does intent debt relate to the earlier critique that specs cannot fully capture implementation?
  Both are true simultaneously: a spec detailed enough to BE the program is just the program in a slower language AND the fact that you cannot capture all intent does not license capturing none of it. The reframe is triage: identify load-bearing decisions and externalize their rationale, not totality.
• ✅ What are the operational levers for paying intent debt down?
  Four: (1) write specs for intent not implementation, (2) treat AGENTS.md as intent ledger not /init-generated config, (3) capture decisions as lightweight ADRs at decision-time, (4) self-improving learnings loops that write intent back into the repo at session-end.
• ⭕ Whose problem is intent debt — individual developers, team leads, tooling vendors, or organizations?
  Osmani addresses the individual-developer level exclusively. He gestures at vendor-level pressure (the '/init' default, AGENTS.md-as-config) but does not propose vendor-level remedies. He does not address organizational incentives that might reward visible agent activity over externalized intent — even though his own diagnosis implies they would. This is the third post in his series where the diagnosis is structural and the remedy stays at the individual-practice level.
• ⭕ How does the load-bearing-rationale triage actually work — how do you identify in the moment which rationale will matter later?
  Asserted as the resolution to the 'can't capture everything' objection but not operationalized. No criterion is offered for distinguishing load-bearing from incidental decisions at the moment of decision. The implicit assumption is that developers can do this reliably — an unobvious assumption.
• ⭕ Are AGENTS.md, ADRs, learnings files and specs actually adequate substrates for externalized intent, or just the artifacts that happen to exist?
  Unaddressed. The prescriptions assume the format question is settled. But intent has rich structure (constraints with priorities, non-negotiables vs preferences, historical contingencies vs principled stances, decisions whose conditions might change vs immutable) and current artifact formats are flat. Whether they can actually carry the load is not interrogated.
• ⭕ What about tests that encode intent, not just behavior — is there a fourth paydown lever Osmani hints at but does not develop?
  The second vignette ('the tests never encoded the intent, only the previous behavior') implies intent-specifying tests are possible and would catch a failure class neither prose nor ADRs would catch. But the prescription section moves on to prose-form artifacts (specs, AGENTS.md, ADRs, learnings) without developing the test angle.
• ⭕ What happens to intent debt at the codebase / multi-team scale — are AGENTS.md and ADRs sufficient when intent is distributed across services, teams, and time?
  Unaddressed. The prescriptions are local-to-repo; cross-cutting intent (architectural principles that span services, security postures that span teams, business invariants that span codebases) is not engaged.

Gaps

• incompleteThe recurring Osmani blind spot — third post in a row. Osmani diagnoses a structural problem (intent debt is an artifact-class agents cannot pay down; the cost is now paid per-session-per-agent) and then prescribes individual-developer disciplines. He never engages: (a) organizational incentives that actively reward visible-agent-activity over externalized intent (managers measuring spawn count, throughput pressure that captures any efficiency gain), (b) tooling vendor responsibilities (auto-generated /init flows that produce descriptive AGENTS.md rather than intent-bearing AGENTS.md; UIs that make spawning easy and rationale capture optional), (c) compensation structures that reward shipping over documenting. The individual-discipline frame puts the entire fix-burden on the developer and treats organizational/vendor pressure as background — the same move he made in 'The Orchestration Tax is You' and 'Comprehension Debt'. For Kjetil tracking this series, this is now a load-bearing limitation of Osmani's whole program, not a one-off omission.
  Read next: Paul Reed 'Ironies of A^2 I^2' (already in this repo) on how orgs capture AI efficiency as throughput pressure. John Cutler on institutional overload and how teams metabolize new capabilities — particularly TBM 411-413 you've been tracking. Donella Meadows' leverage points: rule changes and goal changes outrank parameter changes. Greger Wedel-style 'leadership when the org pressures the opposite direction' on what happens when an individual-practice prescription meets organizational counter-pressure.
• incompleteThe operational test for detecting intent debt — 'helplessness, not friction' — is phenomenologically sharp but methodologically thin. No metric is proposed. No instrumentation is suggested. No team-level practice (e.g., 'in code review, mark every line nobody can defend; intent debt = count(undefended) / count(reviewed)') is offered. For a practical post, the diagnostic side is underbuilt relative to the prescriptive side — and the prescriptions cannot be targeted without measurement.
  Read next: DORA-style metrics literature for how engineering practice gets measured; Forsgren/Humble/Kim 'Accelerate' on lead metrics for invisible properties; SPACE framework (GitHub/Microsoft research) for measuring developer experience without distortion; possibly Storey's own follow-up research papers on triple-debt measurement.
  closed byFrom Technical Debt to Cognitive and Intent Debt: Rethinking Software Health in the Age of AI — Storey's paper provides substantially more diagnostic detail than Osmani's derivative treatment: five named signals for cognitive debt (resistance to change, unexpected results, slow onboarding, loss of transactive memory, low bus factor) and three for intent debt (behavior drift, AI agents struggling despite technically correct output, loss of articulated constraints). This partially closes the diagnostic-thinness gap Osmani's g2 raised, though it remains qualitative rather than a proposed metric or instrument -- see this document's own gaps for the remaining quantification shortfall.
• incompleteOsmani concedes 'you can't write down everything' and resolves it as a load-bearingness triage problem — but never gives a criterion for identifying load-bearing decisions IN THE MOMENT (before you know which ones will matter later). This is the operationally hard part. Empirically, much rationale that turns out to be load-bearing did not look load-bearing at decision time. The 'capture the load-bearing why' guidance therefore risks being well-intentioned but unimplementable, or implementable only by people who already have the seniority to predict consequence — i.e., precisely the people whose departure creates the problem in the first place.
  Read next: Naur 'Programming as Theory Building' on what kinds of decisions are reconstructible from code and which are not. Polanyi on tacit vs explicit knowledge. Decision-research literature (Annie Duke, your Thinking in Bets reading) on the inability to predict consequence and how that affects pre-commitment to recording rationale.
• incompleteOsmani treats existing artifact formats (specs, AGENTS.md, ADRs, learnings files) as adequate substrates for externalized intent. But intent has rich structure that current formats are flat against: constraints with priorities, non-negotiables vs preferences, time-bound vs principled choices, contingent vs invariant rationale. He gestures at AGENTS.md being 'the conventions, the 'we don't do it this way because…' — but doesn't interrogate whether prose-form artifacts can actually carry the relational structure between intents that an agent would need to reason about. A fully developed treatment would distinguish intent-as-data (structured, queryable, machine-readable) from intent-as-prose (current state).
  Read next: Knowledge-representation literature (description logics, semantic web). Architecture-decision-record research on what ADRs actually capture vs miss (Michael Nygard's original posts, plus more recent empirical work). Yourdon & Constantine on structured design and what counts as a 'design rationale' (already in the repo).
  closed byComprehension at AI Speed: Building a Context Store for Evolutionary Architecture — Offers a concrete structural answer to the intent-as-data versus intent-as-prose question: the context store's four layers (structure, lineage, behavior, conformance) project into both a machine-readable knowledge graph that agents and CI jobs query and a human-readable system spec, rather than leaving intent as flat, undifferentiated prose.
• incompleteThe second vignette — tests encoded previous behavior, not intent — implies a fourth paydown lever Osmani does not develop: intent-specifying tests. Specification-by-example, BDD/Gherkin, property-based testing with named invariants, and contract tests can all carry intent in a form an agent can both READ and execute against. The prescription section moves entirely to prose-form artifacts and misses this. For Kjetil specifically — given Kent Beck's TCR work and TDD lineage — this is the most under-developed cell of Osmani's argument.
  Read next: Kent Beck's TDD and TCR writing (already in your queue). Specification-by-example literature (Gojko Adzic). Property-based testing's claim to encode intent (Hypothesis docs; QuickCheck papers). David Heinemeier Hansson's writing on tests as documentation. Possibly Andre Arko or Drew Petersen on contract testing as intent capture.
  closed byFrom Technical Debt to Cognitive and Intent Debt: Rethinking Software Health in the Age of AI — Storey's paper explicitly names and develops 'executable intent' (BDD specifications and tests designed to capture purpose, not just verify behavior) as a practice, plus Architecture Decision Records and Domain-Driven Design -- exactly the fourth paydown lever (intent-specifying tests / specification-by-example) Osmani's g5 flagged as implied but undeveloped in his derivative piece.
• incompleteStorey's Triple Debt Model is imported uncritically as the organizing taxonomy. But it is not obviously exhaustive: process debt (the way work flows through the team), dependency debt (third-party choices whose rationale and constraints aren't recorded), data debt (schema and semantic-meaning decisions), and organizational debt (decisions about team structure and ownership) are all candidate fourth (fifth, sixth) categories. The independence claim that does so much work in the post depends on the taxonomy being clean — if intent debt overlaps significantly with one of these others, the agent-paydown asymmetry argument may not generalize cleanly.
  Read next: Margaret-Anne Storey's actual arXiv paper (the post cites it) to see whether she addresses exhaustiveness; broader software-engineering-research literature on debt classifications (Avgeriou, Kruchten); Tom DeMarco's 'Slack' for a process-debt angle.
  closed byFrom Technical Debt to Cognitive and Intent Debt: Rethinking Software Health in the Age of AI — Read directly, Storey's arXiv paper does not address taxonomy exhaustiveness or engage alternative debt categories (process, dependency, data, organizational debt) at all -- confirming that this gap originates in the primary source itself, not merely in Osmani's secondary treatment of it. The gap is not resolved, but the open question 'does Storey address this?' is now answered (no), and is recorded as this document's own g1.
• incompleteOsmani does not engage what happens at the codebase / multi-team scale. Prescriptions are local to a repo (AGENTS.md per repo, ADRs per service, learnings file per session). But the intent that matters most often spans services (an architectural principle), teams (a security posture), and time (a business invariant established long ago). At that scale, prose artifacts in each repo do not compose — they fragment. The post would benefit from an explicit acknowledgement that local-repo paydown does not solve the cross-cutting case, and a gesture at what would.
  Read next: Vlad Khononov on coupling in distributed systems (already shortlisted in your library); the architectural-decision-management literature (Olaf Zimmermann); Chris Richardson's microservices.io patterns on shared architectural concerns; Wardley mapping for cross-cutting intent.
  closed byHow Claude Code works in large codebases: Best practices and where to start — Supplies the multi-team-scale mechanism Osmani's repo-local prescriptions (AGENTS.md per repo, ADRs per service) lacked: plugins bundle and distribute shared conventions across repos/services, and an agent-manager/DRI role plus cross-functional governance working groups are the organizational structure that lets shared context and intent span services rather than staying local to one repo.
• illogicalThe 'agents cannot generate intent because intent is the one input that has to come from a human' premise is treated as structural / informational, but it is asserted rather than argued. A strong-form counterargument exists: agents COULD acquire intent by observing the human in the moment (commit-time prompting: 'what's the rationale for this change?'), by behavioral telemetry (what does the developer test, what do they NOT test, what do users complain about), or by negotiated dialogue (the agent proposes possible intents and the human selects). Osmani's claim that agents can only 'fabricate' intent presupposes a no-interaction model. The interaction-rich model is exactly where the future is heading. Without engaging it, the structural claim is weaker than it sounds.
  Read next: Recent harness-engineering writing (Birgitta Bockeler, already in your library) on interactive intent elicitation. The 'plan first' / 'specs first' agent patterns in Claude Code / Cursor / Codex. Recent multi-agent-systems literature on negotiated specification. Greg Brockman / OpenAI on commit-time prompting flows.
  closed byNew Skills! v1.1 brings /wayfinder, /research, /implement, /to-spec, /to-tickets — PARTIAL, and pattern-not-evidence. That gap argues Osmani's 'agents can only fabricate intent' claim ignores an interaction-rich model where the agent acquires intent by negotiated dialogue (it proposes, the human selects). This video is a shipping instance of exactly that: the grilling skill (p9) interrogates the human one question at a time, explicitly separates facts the agent finds from decisions only the human can make, captures rationale in ADRs and a glossary, and gates on human confirmation — and the flow as a whole (p1) is a 'plan first / specs first' agent pattern of the kind the gap's reading direction seeks. It demonstrates the interactive intent-elicitation pattern rather than settling the philosophical claim.
• incompleteThe series-level pattern is itself worth naming. Comprehension debt → orchestration tax → intent debt is now a tightly linked triptych, and Osmani treats them as cumulatively framing one diagnosis. But he never names the underlying disease. The candidate name — and the missing post — is something like 'externalization debt' or 'legibility debt': all three debts are downstream of a single failure to make the relevant signal (code, mental model, rationale) readable by something other than the senior engineer's head. The post that names that underlying disease, distinguishes it from the symptom-class, and asks what an externalization-first development culture looks like, has not been written. For Kjetil tracking the series, that is the post to ask Osmani for next.
  Read next: Michael Polanyi 'The Tacit Dimension'. Edwin Hutchins 'Cognition in the Wild' on distributed cognition and externalization. Don Norman 'Things That Make Us Smart' on cognitive artifacts. Andy Clark on extended mind. Possibly David Weinberger 'Everything is Miscellaneous' on the conditions under which knowledge externalizes well.

Related documents

• Five studies that are changing how I think about AI in software engineering
  Cognitive Debt Intent Debt Orchestration Tax / Human Review Bottleneck Technical Debt
• From Technical Debt to Cognitive and Intent Debt: Rethinking Software Health in the Age of AI
  Architecture Decision Records Cognitive Debt Intent Debt Technical Debt
• Agentic Code Review
  Cognitive Debt Intent Debt Orchestration Tax / Human Review Bottleneck
• Fragments: February 13
  Cognitive Debt Orchestration Tax / Human Review Bottleneck Technical Debt
• Harness engineering: leveraging Codex in an agent-first world
  Agent Context Files (CLAUDE.md / AGENTS.md) Intent Debt Orchestration Tax / Human Review Bottleneck
• How do software development teams manage technical debt? - An empirical study
  Architecture Decision Records Intent Debt Technical Debt
• The 8 software engineering metrics AI broke
  Cognitive Debt Technical Debt
• AI coding creates two kinds of debt. You're only measuring one
  Cognitive Debt Technical Debt
• AI Enthusiasts Are in a Race Against Time, AI Skeptics Are in a Race Against Entropy
  Cognitive Debt Technical Debt
• The AI-Native SDLC playbook
  Intent Debt Orchestration Tax / Human Review Bottleneck