The Intent Debt — Knowledge Graph Meshup
A knowledge graph collection of Addy Osmani's The Intent Debt (O'Reilly Radar, 2026-08-14), coherently meshed with supplementary content from the agent-rdf-memory skill, Kingsley Uyi Idehen's Agent Skills, Filesystems, and Context Graphs, and The File Create, Save, and Share Paradigm — Revisited. The mesh thesis: intent debt is paid down by externalizing intent into artifacts agents can read, and agent-rdf-memory, Agent Skills, Filesystems/WebDAV, and Context Graphs are the concrete mechanisms for doing that at scale.
Intent Debt Meshup Ontology
Intent Debt — Externalized Intent Ontology
Lightweight ontology for modeling the Triple Debt Model's debt kinds, the practices and mechanisms that externalize intent into artifacts agents can read, and the mesh between The Intent Debt and the supplementary OpenLink/agent-rdf-memory sources.
Debt Kind
The Three Debts
One of the three kinds of software debt in Margaret-Anne Storey's Triple Debt Model: technical, cognitive, or intent debt.
Externalization Mechanism
A mechanism that moves intent out of human heads and into artifacts an agent can read — an RDF memory store, an agent skill, a filesystem interface, or a context graph.
Paydown Practice
A practice for paying down intent debt by externalizing rationale as a first-class artifact.
has debt kind
Links a system, article, or claim to the debt kind it concerns.
externalized via
Links intent or rationale to the mechanism that externalizes it.
kg-generator
Knowledge Graph generation skill of the ai-agent-skills repository: transforms source documents into standards-compliant RDF using curated prompt templates.
rdf-infographic-skill
RDF-based HTML and Markdown infographic generation skill: converts RDF knowledge graphs into interactive, self-contained HTML infographics with a strict harness contract.
DeepSeek V4 Flash
The language model that authored this RDF collection and its HTML/Markdown companions under the ai-agent-skills contract.
ai-agent-skills
OpenLink Software's collection of reusable AI agent skills for querying semantic web data sources, knowledge graphs, and databases.
The Intent Debt
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).
Technical debt lives in the code. Cognitive debt lives in people. Intent debt lives in artifacts — the goals, constraints, and rationale for why the system is the way it is. Intent debt is the one kind of debt agents cannot pay down for you: a model can infer a plausible rationale from code, but a guess about intent is not the intent. The paydown is externalizing the why as a first-class artifact: specs for intent, AGENTS.md as an intent ledger, lightweight decision logs, and learning loops that write intent back down.
intent debt, technical debt, cognitive debt, comprehension debt, Triple Debt Model, AI agents, agentic engineering, externalized rationale, AGENTS.md, decision logs, ADR, agent skills, context graphs, WebDAV, agent-rdf-memory, orchestration tax
The Intent Debt (original)
The original version of The Intent Debt as published on Addy Osmani's blog site; the O'Reilly Radar Substack post is a republication with the author's permission.
The why is the one thing it can only fabricate.
Punch line of The Intent Debt: of the three debts, intent debt is the only one an agent cannot bail you out of — the why is the one thing it can only fabricate. Rendered as the synopsis deck pull-quote.
Three Places Debt Can Live
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.
Technical Debt
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.
Cognitive Debt
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.
Intent Debt
The debt agents can't pay
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.
The three debts are independent
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.
Why Intent Debt Is the One Agents Can't Help With
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.
Agents pay technical debt down
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.
Agents restore comprehension on demand
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.
Intent must originate with 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 invented confident-sounding reason
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.
The why is the one thing it can only fabricate
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.
Agents Make the Unwritten Cost Compound Much Faster
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.
Intent used to move person to person
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.
Agents break the tacit-transfer model
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.
The economics of not writing things down changed
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.
The twenty agents you're so excited to parallelize
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.
Orchestration tax is partly intent-debt tax
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.
The Other Half of the Comprehension Debt Argument
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.
Specs are not a complete answer
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.
No license to capture none of it
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.
Record the load-bearing why
You do have to write down the why behind the choices that would be expensive to get wrong, because nobody will reconstruct those later.
Code is the answer; intent was the question
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.
What High Intent Debt Looks Like
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.'
The deleted guard clause
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.
The refactor that changed behavior
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.
Why do these services talk over a queue?
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, at team scale
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.
Paying It Down: Externalize Intent as a First-Class Artifact
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.
Write the spec for the intent, not the implementation
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.
Treat AGENTS.md as your intent ledger, not your config
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.
Capture decisions where they happen
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.
Make the learning loop write intent back down
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.
Where the Value Moved
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.
Code used to be the scarce asset
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.
Intent is the one input that still originates with a human
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.
Write down the why
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.
The Mesh: Externalized Intent in the OpenLink Data Space
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.
Agent RDF Memory: intent as a queryable artifact
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.
Agent Skills: intent encapsulated as capability
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: the lowest-friction intent artifact layer
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.
Context Graphs: meaning as a materialized view
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 retrieval protocol: intent read before action
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.
Synthesis: intent debt is the artifact-side debt
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.
Related Reading
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.
Comprehension Debt
Addy Osmani's companion post on comprehension debt — the erosion of shared understanding — which intent debt sharpens and complements.
The Orchestration Tax
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.
Cognitive Surrender
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.
A Good Spec
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.
Stop Using /init: AGENTS.md
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.
Automated Decision Logs
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.
Self-Improving 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.
Agent Skills, Filesystems, and Context Graphs: Collapsing Software Complexity at the Root
Agent Skills, Filesystems, and Context Graphs
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.
The File Create, Save, and Share Paradigm — Revisited
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 Triple Debt Model
The Triple Debt Model (Margaret-Anne Storey et al.)
The paper behind the three models of software health — technical, cognitive, and intent debt — that The Intent Debt builds on.
Beyond the 'context graph' (memory), we need brain, CNS, hand and legs — a five-pillar architecture in production: memory (context of decisions made), brain/inference (from storing data to active reasoning), nervous system/dataflows (orchestrating across siloed systems), hands/engagement (rendering insights where work happens), and legs/governance (the unsexy RBAC, security, and reliability layer that lets the system stand).
This looks very aligned with how I'm also working — can you share that NotebookLM PDF separately?
I clearly forgot to share the NotebookLM PDF. Here's the link: https://www.openlinksw.com/data/pdf/Agents_Files_Context_Structural_Convergence.pdf
Addy Osmani
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.
Kingsley Uyi Idehen
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.
Margaret-Anne Storey
Professor of Computer Science at the University of Victoria and Canada Research Chair; software engineering researcher and author of the Triple Debt Model.
Tim Berners-Lee
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.
Dave Winer
Software developer and blogging pioneer; creator of Radio UserLand and the OPML format; his work made the create-save-share paradigm accessible to authors.
Karpagam Narayanan
Commenter on the Agent Skills, Filesystems, and Context Graphs article; proposes a five-pillar production agent architecture (memory, inference, dataflows, engagement, governance).
Dinis Cruz
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.
O'Reilly Media
Technology learning company publishing books, courses, and the O'Reilly Radar publication; parent of the O'Reilly Radar Substack.
O'Reilly Radar
O'Reilly's publication on the trends shaping tech, hosted on Substack; publisher of The Intent Debt.
AI & Data Driven Enterprise
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.
OpenLink Software
Developer of Virtuoso, OPAL, and the ai-agent-skills repository; founded by Kingsley Uyi Idehen.
Google
Technology company; Addy Osmani's former employer as an engineering leader.
University of Victoria
Canadian university where Margaret-Anne Storey is a professor of computer science and Canada Research Chair.
World Wide Web Consortium
International standards organization for the Web, co-directed by Tim Berners-Lee.
Anthropic
AI safety and research company; maker of the Claude AI assistant mentioned in The File Create, Save, and Share Paradigm — Revisited.
OpenAI
AI research and deployment company; maker of ChatGPT, mentioned in The File Create, Save, and Share Paradigm — Revisited.
LinkedIn
Professional networking platform whose Pulse publishing surface hosts the two supplementary Idehen articles.
OPAL (OpenLink AI Layer)
OpenLink AI Layer: simplifies Agent and Agent Skill creation by letting domain experts work in Markdown rather than code-heavy frameworks. Skills are declared, not engineered; intent, data access, and constraints live together; deployment becomes configuration-driven; skills stay loosely coupled to underlying data spaces; MCP/A2A compliant.
Virtuoso
OpenLink's multi-model DBMS (SQL, SPARQL, GraphQL, RDF quad store, WebDAV filesystem). Extends its model by transparently exposing DBMS capabilities through a filesystem interface via WebDAV: SQL and SPARQL query results materialized as files, context graphs as directories and documents.
ChatGPT
OpenAI's AI assistant; cited in The File Create, Save, and Share Paradigm — Revisited as one of the modern writing tools that make content creation faster while ownership and distribution remain open questions.
Claude
Anthropic's AI assistant; cited in The File Create, Save, and Share Paradigm — Revisited as a modern writing tool for Web-style publishing.
Gemini
Google's AI assistant; cited in The File Create, Save, and Share Paradigm — Revisited as a modern writing tool for Web-style publishing.
Radio UserLand
Dave Winer's blogging tool that enabled authors to publish HTML documents and syndicate content easily via RSS, Atom, and OPML, fostering an open ecosystem of publication and subscription.
agent-rdf-memory
OpenLink's Agent RDF Memory skill: a queryable behavioral contract for AI agents encoded as RDF-Turtle — core.ttl (identity and output routing), preferences.ttl (hub-and-spoke schema:HowTo of 200+ HowToStep rules), index.ttl (session index), sessions/ (episodic memory), howto/ (specifications), entities/ (registry), and a mandatory retrieval protocol. The operationalized intent ledger.
The queryable behavioral contract hub: a schema:HowTo (agentBehaviorGuide) with schema:hasPart sub-HowTos and 200+ schema:HowToStep entries — the standing rules an agent must follow, i.e., the intent ledger made queryable.
Long-term knowledge: user identity, agent identity template, and output-path routing for generated artifacts.
Summary index of sessions and files — a schema:ItemList of schema:ListItem entries pointing at every session file.
sessions/
Episodic memory: one Turtle file per day, LLM, and agent environment, recording prompts, tasks, artifacts, decisions, and lessons — the decision log at infrastructure scale.
howto/
Companion specification files, one per sub-HowTo, carrying the full rationale, code, gates, and incident notes referenced by preferences.ttl steps.
entities/
Registry of people, organizations, tools, and concepts with canonical IRIs — the shared identity layer of the memory store.
Custom vocabulary: prompt-intent classes, retrieval policies, and ontology-routed context-selection rules.
agent-rdf-memory/AGENTS.md
The prose entry point of the memory protocol: mandatory retrieval sequence, folder structure, session naming, storage rules, and enforcement — the intent ledger read before every task.
Frequently Asked Questions
Fifteen questions about intent debt and its mesh with agent-rdf-memory, Agent Skills, Filesystems, and Context Graphs.
What is intent debt?
Intent 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.
How does intent debt differ from technical and cognitive debt?
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.
Why can't AI agents pay down intent debt?
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.
Why do agents make the cost of unwritten intent compound?
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.
What does high intent debt look like in practice?
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.
What is the paydown for intent debt?
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.
What is the difference between a spec for intent and a spec for implementation?
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.
Why should AGENTS.md be treated as an intent ledger?
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.
What role do decision logs (ADRs) play in paying down intent debt?
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.
How does agent-rdf-memory externalize agent intent?
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.
How do Agent Skills relate to intent debt?
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.
How do filesystems and WebDAV help externalize intent?
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.
What is a context graph and how does it relate to externalized intent?
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.
How does the create-save-share paradigm apply to intent artifacts?
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.
Is intent debt the same as cognitive debt?
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.
Glossary of Terms
Sixteen terms spanning the Triple Debt Model and the externalization mechanisms of the mesh.
Erosion of shared understanding — the gap between how much code exists and how much any human understands; also called comprehension debt.
Triple Debt Model
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.
Externalized Rationale
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.
Agent Skill
A reusable, composable capability that encapsulates intent, constraints, access to data/information/knowledge, and a repeatable workflow pattern, discoverable and invocable by agents.
Context Graph
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.
Materialized View
A precomputed, queryable result of a declarative specification — in the mesh, the pattern by which context graphs manifest meaning as consumable artifacts.
Filesystem Interface
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.
WebDAV
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.
OPAL
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.
Architecture Decision Record
A lightweight, dated record of a decision and its rationale, captured where the decision happens — pure intent-debt paydown.
Orchestration Tax
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.
Intent Ledger
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.
Create-Save-Share Paradigm
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.
Definition of Done
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.
Self-Improving Agent
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.
Paying Down Intent Debt: Externalize Intent as a First-Class Artifact
Seven steps — four from the article's paydown practices and three meshing in the supplementary OpenLink/agent-rdf-memory mechanisms — for moving intent out of human heads and into artifacts agents can read.
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.
Capture decisions where they happen with lightweight ADRs
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.
Externalize agent intent as queryable RDF (the agent-rdf-memory pattern)
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.
Package intent, constraints, and workflows as Agent Skills
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.
Publish intent artifacts through filesystem interfaces and feeds
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.
Intent rules in the agent memory store
SPARQL
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 ?step
Finds the behavioral-contract rules in preferences.ttl that operationalize intent externalization — the intent ledger made queryable.
SPARQL SELECT
Session artifacts (episodic intent records)
PREFIX schema: <http://schema.org/> SELECT ?session ?artifact ?format WHERE { ?session a schema:CreativeWork ; schema:result ?artifact . ?artifact schema:fileFormat ?format . } LIMIT 25
Lists sessions and the RDF/HTML/MD artifacts they produced — the decision log at infrastructure scale, queryable across the session index.
Debt kinds in this knowledge graph
PREFIX : <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 ?debt
Returns the three debt kinds of the Triple Debt Model as modeled in this collection.