Technical debt lives in your code. Cognitive debt lives in your head. Intent debt lives in the artifacts you may never have written — and it is the one debt your agents cannot pay down for you.
Technical debt lives in your code. Cognitive debt lives in your head. Intent debt lives in the artifacts you may never have written: the goals, constraints, and rationale for why the system is the way it is. It is the one kind of debt your agents cannot pay down for you — and agentic engineering makes it the most expensive.
Addy Osmani's The Intent Debt (O'Reilly Radar, 2026-08-14, republished from addyosmani.com with the author's permission) builds on Margaret-Anne Storey's Triple Debt Model: technical debt accumulates in code, cognitive debt erodes shared understanding in people, and intent debt is the absence or erosion of the externalized rationale that explains why a system is the way it is. Because agents start every session cold and fabricate plausible rationales for decisions they never made, unexternalized intent now accrues interest every session, multiplied by every agent on the team.
The paydown is externalization: write the spec for the intent, treat AGENTS.md as an intent ledger, capture decisions where they happen, and make the learning loop write intent back down. This collection meshes that thesis with three supplementary sources — the agent-rdf-memory skill (a queryable RDF behavioral contract that externalizes agent intent as a first-class artifact), Kingsley Uyi Idehen's Agent Skills, Filesystems, and Context Graphs (the convergence architecture in which skills encapsulate intent, filesystems carry artifacts, and context graphs materialize meaning), and The File Create, Save, and Share Paradigm — Revisited (WebDAV and Briefcase as the distribution layer for intent artifacts humans and agents can both read).
View this analysis as a KG entity“The why is the one thing it can only fabricate.” — Addy Osmani
Margaret-Anne Storey's Triple Debt Model is a clean way to think about software health: technical debt lives in the code, cognitive debt lives in people, and intent debt lives in artifacts. The three are independent — you can have low technical debt and high intent debt — and each one bills you separately.
Accumulation of implementation choices that make the system harder to change later: the tangled module, the shortcut taken under deadline, the abstraction that leaked. Understood for decades; felt through slow builds, fragile tests, and the dread of touching one particular file.
Erosion of shared understanding — the gap between how much code exists and how much any human understands; Osmani calls it comprehension debt. Builds up when the system grows faster than the team's mental model, so pristine code can still carry crippling cognitive debt.
Absence or erosion of the externalized rationale, goals, and constraints that explain why the system is the way it is. The key word is externalized: rationale must be written down where a teammate, a future you, or an agent can read it. When intent debt runs high, the system drifts from what you meant it to do.
You can have low technical debt and high intent debt. You can understand a system completely yourself while its intent exists nowhere outside your skull — enormous intent debt for everyone else. From the inside they feel alike, but each one bills you separately.
AI makes technical debt cheaper to take on and cheaper to pay down, and cognitive debt recovers more easily than most engineers expect. Intent is different: an agent cannot generate intent, because intent is the one input that has to come from you. A guess about intent is not the intent.
AI generates code faster than ever, which makes technical debt cheaper to take on and cheaper to pay down. Point an agent at a tangled module and it will refactor it.
When you don't understand a chunk of the system, you ask the agent to explain it and rebuild part of the lost mental model on demand, because the code still exists and the model can read it back to you.
An agent can't generate intent, because intent is the one input that has to come from you. A model can infer a plausible rationale from the code, the same way you can guess why a previous engineer did something — but a guess about intent isn't the intent.
The model doesn't know whether that 300ms debounce was a deliberate UX decision, a benchmark result, or a number someone typed once and never revisited. It will invent a confident-sounding reason, which is worse than admitting it doesn't know.
Of the three debts, intent debt is the only one where the agent can't bail you out. It can write the code and restore your comprehension. The why is the one thing it can only fabricate.
Teams got away with high intent debt for years because intent moved person to person — hallway conversations, code review comments, the engineer who had been there four years as walking intent documentation. Agents break that model: each one is a teammate who has never met you, starts sessions cold, and fills every gap with a plausible guess.
When a new human joined a team, you didn't write everything down: intent was picked up over time through hallway conversations, code review comments, and 'we don't do it that way because of an incident in 2023.' The four-year engineer was the intent documentation — expensive and lossy, but it worked.
Bringing agents onto a team doubles its size overnight with junior people who have no long-term memory. An agent starts most sessions cold and carries none of the tacit intent humans built up over years. Whatever you haven't externalized into an artifact it can read, it doesn't have.
Unexternalized intent used to cost you once in a while, at onboarding or after someone left. Now you pay it every session, multiplied by every agent you run.
Each one is a teammate who has never met you, can't read your mind, and will fill any gap in your intent with a plausible guess. The orchestration tax is partly an intent-debt tax: much of what makes managing many agents exhausting is resupplying the intent you never wrote down.
Much of what makes managing many agents exhausting is resupplying the intent you never wrote down — the orchestration tax Osmani wrote about is partly an intent-debt tax.
Detailed specs aren't a complete answer — a spec detailed enough to be the program is the program in a slower language. Intent debt is the complementary truth: being unable to capture all intent is no license to capture none of it. Code is the answer; the intent was the question it was meant to solve.
Translating a spec into working code involves a huge number of implicit decisions no spec ever captures, and a spec detailed enough to be the program is the program in a slower language.
Being unable to capture all intent is no license to capture none of it. The implicit decisions an agent now makes on your behalf, the ones a spec will never enumerate, are the decisions whose rationale evaporates if you don't record at least the load-bearing ones.
You do have to write down the why behind the choices that would be expensive to get wrong, because nobody will reconstruct those later.
Comprehension debt warns you not to trust that code is correct because it exists. Intent debt warns you not to trust that the reason survives because the code does. AI is brilliant at producing answers to questions you forgot to write down.
Intent debt rarely shows up as friction; it shows up as a particular kind of helplessness: a guard clause deleted and no one can say whether it was load-bearing, a refactor that changed behavior the tests never encoded, a queue where the honest answer is 'an agent suggested it and it seemed fine.'
An agent 'fixes' a bug by deleting a guard clause, and nobody can say whether that guard was load-bearing or leftover, because no doc or commit message ever recorded why it was there.
A refactor changes a behavior users depend on. The review passed because the diff looked clean and the tests were green, but the tests only encoded the previous behavior, never the intent.
You ask why two services talk over a queue instead of a direct call, and the honest answer is 'an agent suggested it and it seemed fine.' That answer is intent debt, already accruing interest.
Cognitive surrender is defending a design choice you can't reconstruct — your own posture in the moment. Intent debt is what a hundred of those moments leave in the repo for the next person and the next agent to inherit.
Almost everything Osmani has been writing about for months turns out to be intent-debt management. The move is the same each time: take the intent out of your head and put it somewhere an agent can read — a spec for intent, AGENTS.md as an intent ledger, lightweight decision logs, and a learning loop that writes intent back down.
A good spec captures the goals, the constraints, the nonnegotiables, and an explicit definition of done — fast, accessible, secure, delightful, beyond 'functionally correct.' The spec carries the intent the code can't carry on its own.
An auto-generated file describes what the code is. An intent file describes what the team means: the conventions, the 'we don't do it this way because,' the constraints invisible in any single file. Agents can't infer that, and they need it most.
Lightweight decision logs (ADRs) are pure intent-debt paydown. Recording why at the moment you decide costs almost nothing; reconstructing it eight months later, after the person who knew why has moved teams, costs a fortune. Agents have made logging cheaper than ever, so the old excuse is gone.
Self-improving agents update a learnings file at the end of a session. The same loop is an intent-debt pump running in reverse: every mistake whose root cause you've recorded, every 'we tried X and it didn't work because Y,' is intent that would otherwise have lived only in your memory of a bad afternoon.
For a long time the scarce, valuable thing in software was the ability to produce a correct implementation; code was expensive, so we optimized for writing it. AI made code cheap and comprehension recoverable. Intent — the goals, constraints, and reasons — is the one input that still has to originate with a human, and the one we're worst at externalizing.
For a long time, the scarce, valuable thing in software was the ability to produce a correct implementation. Code was expensive, so we optimized for writing it.
AI made code cheap, and comprehension is recoverable. Intent, the goals and constraints and reasons, is the one input that still has to originate with a human — and the one we're worst at externalizing, because for decades we got away with carrying it in our heads.
Technical debt makes your system hard to change. Cognitive debt makes it hard to understand. Intent debt makes it hard to know whether the system still does what you wanted, and it's the only one of the three your agents can't pay back for you. Write down the why, because it's becoming the most valuable thing you can leave in the repo.
Addy Osmani's paydown practices are not abstract: this collection meshes them with three supplementary sources that operationalize externalized intent. The agent-rdf-memory skill is the AGENTS.md-as-intent-ledger practice made concrete — a queryable RDF behavioral contract an agent must read before every task. Idehen's Agent Skills, Filesystems, and Context Graphs provides the convergence architecture: skills encapsulate intent, filesystems carry artifacts, and context graphs materialize meaning. And The File Create, Save, and Share Paradigm — Revisited supplies the distribution layer: WebDAV and Briefcase publishing intent artifacts where humans and agents can both read them.
The agent-rdf-memory skill and store externalize an agent's behavioral contract as RDF-Turtle: preferences.ttl is a hub-and-spoke schema:HowTo of 200+ HowToStep rules (the operationalized intent ledger), core.ttl pins identity, sessions/ records episodic decisions per day and agent, howto/ carries full specifications, entities/ is the registry, and a mandatory retrieval protocol makes the agent read that intent before every task. This is 'treat AGENTS.md as your intent ledger' executed as infrastructure.
From Idehen's Agent Skills, Filesystems, and Context Graphs: a skill reframes software functionality as a reusable, composable capability that encapsulates intent, constraints, access to data/information/knowledge, and a repeatable workflow pattern. OPAL lowers the creation barrier so domain experts declare skills in Markdown rather than code — skills are declared, not engineered — shifting value from application ownership toward expertise, verification, and trust.
Filesystems re-emerge not because they are simplistic but because they are universally understood: a stable abstraction, human- and machine-friendly access, natural scoping of context, and compatibility with decades of tooling. Inputs look like documents, outputs look like documents, and intermediate results can be persisted, inspected, and reused. Modern systems treat filesystems as interfaces, not primitive storage — the create-save-share paradigm revisited via WebDAV.
A context graph is a materialized view over data, information, and knowledge, scoped to a particular task or intent: entity-relationship graphs constructed using standardized identifiers, derived using declarative constraints, manifested in consumable forms — often as files. Declarative query languages already solve constraint definition, scope control, and result materialization; what changed is that AI agents can now use these graphs directly rather than merely store them. The externalized why becomes queryable.
The agent-rdf-memory mandatory sequence — list the store, read core.ttl, preferences.ttl, index.ttl, ontology.ttl, then follow rdfs:seeAlso references — is the operationalized version of Osmani's 'treat AGENTS.md as your intent ledger': intent is read, not guessed, before any task executes, and written back after meaningful work.
The Triple Debt Model maps cleanly onto the convergence architecture: technical debt lives in code, cognitive debt lives in people, intent debt lives in artifacts — and Agent Skills, Filesystems, and Context Graphs are artifact infrastructure that pays intent debt down structurally. A skill packages the why of a workflow; a filesystem carries the written-down rationale; a context graph materializes it as queryable meaning. Write the why once, and it compounds for every agent that reads it.
The article's inline references — Osmani's companion posts — plus the two supplementary Idehen articles and the Triple Debt Model paper that anchor this mesh.
Addy Osmani's companion post on comprehension debt — the erosion of shared understanding — which intent debt sharpens and complements.
Addy Osmani's post on the cost of managing many agents — partly an intent-debt tax, since much of the exhaustion is resupplying intent that was never written down.
Addy Osmani's post on defending design choices you can't reconstruct — the personal-posture version of the same hole that intent debt leaves at team scale.
Addy Osmani's post on writing specs that capture goals, constraints, nonnegotiables, and an explicit definition of done — the spec for intent, not the implementation.
Addy Osmani's post arguing that AGENTS.md should be an intent file — what the team means — not an auto-generated description of what the code is.
Addy Osmani's post on lightweight ADRs as pure intent-debt paydown — recording why at the moment you decide, made cheaper than ever by agents.
Addy Osmani's post on agents that update a learnings file at the end of a session — a learning loop that writes intent back down.
Kingsley Uyi Idehen's thesis (LinkedIn Pulse, 2026-01-18): the real breakthroughs come not from new application categories but from a convergence of Agent Skills, Filesystems, and Context Graphs — structurally addressing the translation tax of accidental complexity. OPAL lowers the skill-creation barrier; Virtuoso exposes DBMS capabilities through a WebDAV filesystem interface; the future of software is context-centric.
Kingsley Uyi Idehen's essay (LinkedIn Pulse, 2025-07-19): before HTTP, data was held captive in application-specific documents; URIs, HTTP, HTML, and RDF liberated it. The create-save-share paradigm — modernized with Virtuoso's Briefcase and WebDAV — lets authors write with AI tools, save to public folders, syndicate via RSS/Atom/OPML, add metadata, and control access, reviving decentralized standards-based publishing.
The paper behind the three models of software health — technical, cognitive, and intent debt — that The Intent Debt builds on.
Former engineering leader at Google, bestselling Amazon author, award-winning engineer and international speaker. Author of The Intent Debt; writes about software engineering, motivation, and leadership.
Founder & CEO of OpenLink Software; creator of Virtuoso; Semantic Web pioneer. Author of Agent Skills, Filesystems, and Context Graphs and The File Create, Save, and Share Paradigm — Revisited.
Professor of Computer Science at the University of Victoria and Canada Research Chair; software engineering researcher and author of the Triple Debt Model.
Inventor of the World Wide Web — URIs, URLs, HTTP, and HTML — and co-director of the World Wide Web Consortium; his Web foundations underpin the create-save-share paradigm revisited in the supplementary sources.
Software developer and blogging pioneer; creator of Radio UserLand and the OPML format; his work made the create-save-share paradigm accessible to authors.
Commenter on the Agent Skills, Filesystems, and Context Graphs article; proposes a five-pillar production agent architecture (memory, inference, dataflows, engagement, governance).
Commenter on the Agent Skills, Filesystems, and Context Graphs article; independent application security researcher who found the structural-convergence approach aligned with his own work.
Technology learning company publishing books, courses, and the O'Reilly Radar publication; parent of the O'Reilly Radar Substack.
O'Reilly's publication on the trends shaping tech, hosted on Substack; publisher of The Intent Debt.
LinkedIn publication page by Kingsley Uyi Idehen (4,006 followers) hosting his Pulse articles, including Agent Skills, Filesystems, and Context Graphs and The File Create, Save, and Share Paradigm — Revisited.
Developer of Virtuoso, OPAL, and the ai-agent-skills repository; founded by Kingsley Uyi Idehen.
Technology company; Addy Osmani's former employer as an engineering leader.
Canadian university where Margaret-Anne Storey is a professor of computer science and Canada Research Chair.
International standards organization for the Web, co-directed by Tim Berners-Lee.
AI safety and research company; maker of the Claude AI assistant mentioned in The File Create, Save, and Share Paradigm — Revisited.
AI research and deployment company; maker of ChatGPT, mentioned in The File Create, Save, and Share Paradigm — Revisited.
Professional networking platform whose Pulse publishing surface hosts the two supplementary Idehen articles.
Interactive graph visualization derived from the companion RDF. Click nodes to resolve, drag to explore. Graph data embedded from companion RDF at generation time.
Query this knowledge graph on URIBurner. The editor opens on the canonical SAMPLE entity-type summary (DAV named graph). Pick a recipe, edit freely, then run live or copy.
Reproduced verbatim from the companion RDF. Execute loads the query into the workbench below and runs it live.
PREFIX schema: <http://schema.org/>
SELECT ?step ?name WHERE {
?howto schema:step ?step .
?step schema:name ?name .
FILTER(CONTAINS(LCASE(?name), "intent")
|| CONTAINS(LCASE(?name), "agents.md")
|| CONTAINS(LCASE(?name), "decision"))
} ORDER BY ?stepPREFIX schema: <http://schema.org/>
SELECT ?session ?artifact ?format WHERE {
?session a schema:CreativeWork ;
schema:result ?artifact .
?artifact schema:fileFormat ?format .
} LIMIT 25PREFIX : <https://oreillyradar.substack.com/p/the-intent-debt#>
PREFIX schema: <http://schema.org/>
SELECT ?debt ?name WHERE {
?debt a :DebtKind ;
schema:name ?name .
} ORDER BY ?debtIntent debt is the absence or erosion of the externalized rationale, goals, and constraints that explain why a system is the way it is. The key word is externalized: the why must be written down where a teammate, a future you, or an agent can read it, not held in your head. When intent debt runs high, the system drifts from what you meant it to do, and nobody can say when it diverged or why.
Technical debt lives in the code — implementation choices that make change harder. Cognitive debt lives in people — the gap between how much code exists and how much anyone understands. Intent debt lives in artifacts — the missing externalized why. The three are independent: you can have low technical debt and high intent debt, and each one bills you separately.
An agent can refactor tangled code and restore comprehension by reading code back to you, but intent is the one input that has to originate with a human. A model can only infer a plausible rationale from the code — a guess about intent is not the intent — and a confident-sounding invented reason is worse than admitting it doesn't know. The why is the one thing it can only fabricate.
Teams used to absorb intent through hallway conversations, code review comments, and long tenure — the four-year engineer was the intent documentation. Agents start every session cold, carry none of that tacit intent, and fill any gap with a plausible guess. Unexternalized intent that once cost you once in a while now costs you every session, multiplied by every agent you run.
An agent 'fixes' a bug by deleting a guard clause and nobody can say whether it was load-bearing or leftover; a refactor changes behavior users depend on while tests only encoded the previous behavior, never the intent; and the honest answer to 'why do these services talk over a queue?' is 'an agent suggested it and it seemed fine.' Intent debt shows up as a particular kind of helplessness.
Externalize intent as a first-class artifact: write the spec for the intent not the implementation, treat AGENTS.md as an intent ledger, capture decisions where they happen in lightweight ADRs, and make the learning loop write intent back down. Take the intent out of your head and put it somewhere an agent can read.
An implementation spec describes what the code does. A spec for intent captures the goals, the constraints, the nonnegotiables, and an explicit definition of done — fast, accessible, secure, delightful, beyond 'functionally correct.' The spec carries the intent the code can't carry on its own.
An auto-generated file describes what the code is. An intent file describes what the team means: the conventions, the 'we don't do it this way because' history, the constraints invisible in any single file. Agents can't infer those, and they need them most — so stop using /init and write the intent down.
Recording why at the moment you decide costs almost nothing; reconstructing it eight months later, after the person who knew why has moved teams, costs a fortune. Lightweight decision logs are pure intent-debt paydown, and agents have made logging cheaper than ever, so the old excuse is gone.
It encodes the behavioral contract as queryable RDF-Turtle: preferences.ttl is a hub-and-spoke schema:HowTo of 200+ HowToStep rules (the intent ledger), core.ttl pins identity and output routing, sessions/ records episodic decisions per day and agent, howto/ carries full specifications, entities/ is the registry — and a mandatory retrieval protocol makes the agent read that intent before every task. It is 'treat AGENTS.md as your intent ledger' executed as infrastructure.
A skill reframes functionality as a reusable, composable capability that encapsulates intent, constraints, access to data/information/knowledge, and a repeatable workflow pattern. Packaging intent inside a skill is externalization: the why of a workflow becomes an artifact agents can discover, invoke, combine, and verify — instead of a plausible guess. OPAL lets domain experts declare those skills in Markdown.
Filesystems are the lowest-friction artifact layer: inputs look like documents, outputs look like documents, and intermediate results can be persisted, inspected, and reused. Virtuoso's WebDAV interface materializes SQL and SPARQL results and context graphs as files; the Briefcase adds create-save-share publishing with auto-generated RSS, Atom, and OPML feeds, optional metadata, and attribute-based access control — decentralized standards-based publishing without surrendering control.
A context graph is a materialized view over data, information, and knowledge, scoped to a particular task or intent: entity-relationship graphs constructed with standardized identifiers, derived using declarative constraints, and manifested in consumable forms — often as files. Declarative query languages already solve constraint definition, scope control, and result materialization; what changed is that agents can now use these graphs directly. It turns the externalized why into something queryable.
Before HTTP, data was held captive in application-specific documents. URIs, HTTP, HTML, and RDF liberated it — unambiguous naming, negotiable content types, hypertext, and hyperdata. The create-save-share paradigm — writing into a public folder like /html/, syndicating via RSS, Atom, and OPML, adding metadata, controlling access — is the distribution layer that puts externalized intent where both humans and agents can read it.
No — they are complementary truths. Cognitive (comprehension) debt is the erosion of shared understanding in people; intent debt is the absence of externalized rationale in artifacts. Comprehension debt warns you not to trust that code is correct because it exists; intent debt warns you not to trust that the reason survives because the code does. Code is the answer; the intent was the question it was meant to solve.
Erosion of shared understanding — the gap between how much code exists and how much any human understands; also called comprehension debt.
Margaret-Anne Storey's framework of three independent models of software health: technical debt in code, cognitive debt in people, and intent debt in artifacts.
The goals, constraints, and reasons behind a system written down where a teammate, a future you, or an agent can read them — the opposite of intent held only in a human head.
A reusable, composable capability that encapsulates intent, constraints, access to data/information/knowledge, and a repeatable workflow pattern, discoverable and invocable by agents.
A materialized view over data, information, and knowledge, scoped to a particular task or intent: an entity-relationship graph built with standardized identifiers, derived with declarative constraints, and manifested in consumable forms such as files.
A precomputed, queryable result of a declarative specification — in the mesh, the pattern by which context graphs manifest meaning as consumable artifacts.
Treating a filesystem as an interface rather than primitive storage: inputs look like documents, outputs look like documents, and intermediate results can be persisted, inspected, and reused.
Web Distributed Authoring and Versioning (RFC 4918): an HTTP extension that turns a server into an authorable filesystem, letting DBMSs expose SQL/SPARQL results and context graphs as files and folders.
OpenLink AI Layer: Markdown-driven Agent and Agent Skill definition in which skills are declared, not engineered — intent, data access, and constraints live together and deployment becomes configuration-driven.
A lightweight, dated record of a decision and its rationale, captured where the decision happens — pure intent-debt paydown.
The cost of managing many agents — partly an intent-debt tax, since much of the exhaustion is resupplying the intent you never wrote down.
The personal posture of defending a design choice you can't reconstruct; intent debt is the team-scale, written-down version of the same hole.
A durable, readable record of what a team means — conventions, constraints, and 'we don't do it this way because' history — such as an authored AGENTS.md or an RDF behavioral contract.
The minimal publishing pattern of the early Web — create content, save it into a public folder, and share it via open syndication — modernized with WebDAV, Briefcase, and RSS/Atom/OPML feeds.
The explicit quality bar of a spec for intent — fast, accessible, secure, delightful, beyond 'functionally correct' — that carries intent the code cannot carry on its own.
An agent that updates a learnings file at the end of a session — a learning loop that writes intent back down instead of leaving it in memory.
Capture the goals, the constraints, the nonnegotiables, and an explicit definition of done — fast, accessible, secure, delightful, beyond 'functionally correct.' The spec carries the intent the code cannot carry on its own.
Describe what the team means: the conventions, the 'we don't do it this way because' history, and the constraints invisible in any single file. Agents cannot infer these, and they need them most — stop using /init and author the intent file.
Record why at the moment you decide: it costs almost nothing then, and reconstructing it eight months later — after the person who knew why has moved teams — costs a fortune. Agents have made logging cheaper than ever, so the old excuse is gone.
End sessions by updating a learnings file: every mistake whose root cause you record, every 'we tried X and it didn't work because Y,' is intent that would otherwise live only in your memory of a bad afternoon.
Encode the behavioral contract as RDF-Turtle: a preferences.ttl hub of schema:HowToStep rules, core.ttl identity, episodic session files, companion howto specifications, and an entity registry — with a retrieval protocol that makes the agent read intent before every task and write decisions back afterward.
Define skills as reusable capabilities that encapsulate intent, constraints, data access, and a repeatable workflow pattern — declared in Markdown via OPAL — so agents discover, invoke, combine, and verify what a team means instead of guessing.
Save outputs to structured public folders — WebDAV /html/, /screencasts/, /screenshots/ — that auto-generate RSS, Atom, and OPML feeds, carry optional metadata for discovery, and apply attribute-based access control, so externalized intent reaches humans and agents alike.