# Context Capsules™ ## What A Context Capsule is a structured way to describe any concept in a business so that any consumer, human or AI, has the minimum viable context to act on it correctly. Not to understand it. To **act on it**, without making the mistakes the last person made. A concept can be anything: a product, a team, a role, a process, a metric, a customer segment, an API, a strategy, the company itself. If someone needs context to work with it, it's a candidate for a capsule. Every organisation already has capsules. They're just informal, inconsistent, incomplete, and locked inside people's heads. A Context Capsule makes that context explicit, portable, and persistent. --- ## Who Capsules are written by the people who hold the context today. The domain expert, the team lead, the person who's answered the same question three times. They don't need to be technical. They need to know where the landmines are. In practice, the best capsules often come from a conversation, not a writing session. The person who holds the context talks. Someone else (a scribe, a colleague, an AI) extracts the structure. The expert reviews and approves. This works because domain experts are usually better at explaining than writing, and the Bounds and Gotchas that matter most are often tacit knowledge that only surfaces when someone asks the right questions. Capsules are consumed by anyone who needs to act on the concept. A new hire getting up to speed. A product manager scoping a feature. An AI agent generating code. A data analyst building a report. A CEO briefing an investor. The capsule doesn't care who's reading it. It cares that the reader can act without a 45-minute briefing from the one person who knows. --- ## Why Organisations leak context. Constantly. Through turnover, reorgs, growth, role changes, and simple forgetfulness. The knowledge that makes a business actually work lives in the heads of a handful of people. When those people are unavailable, on holiday, in a different meeting, or gone, everyone else guesses. Sometimes they guess right. Often they don't, and nobody notices until the damage is done. This has always been a problem. Three things are making it urgent: **AI is context-hungry but context-blind.** AI tools will confidently use whatever you give them. They have no way to know what's missing, what's out of scope, or what hidden rule will trip them up. A bigger context window doesn't fix this; it makes it worse. More information without bounds is just more noise. AI needs small, high-signal, bounded context to be genuinely useful. Without it, you get hallucination. With it, you get a specialist. **The pace has changed.** Organisations move faster than documentation can keep up. Wikis rot. Confluence pages go stale. Onboarding decks reflect last year's reality. The gap between what's written down and how things actually work gets wider every quarter. Traditional documentation fails because it's treated as a record. A capsule works because it's treated as operational context: the briefing you'd give someone before they start, not the textbook you'd hand them after. **Building has become iterating.** When the context for a concept already exists in a capsule, creating something new isn't starting from scratch. It's building on institutionalised knowledge. The capsule for your revenue model becomes the starting point for a new pricing feature. The capsule for your customer segment becomes the brief for a new campaign. The capsule for your team becomes the onboarding pack for the next hire. Everything new is an iteration on what's already been captured and pressure-tested. Write the capsule first, and the building gets faster every time. When you capsule a concept, the effects compound. AI gets dramatically less wrong. People ramp faster. And the business becomes queryable: you can ask "what does this team actually do, what are their constraints, and what will go wrong if I assume X" and get an answer that includes the stuff nobody normally writes down. Stack them. Just build. A single capsule eliminates the reconstruction tax for one concept. A stack eliminates it for an entire domain. Company context. System context. Customer context. Product context. Stack the capsules. Hand them to any agent. Watch it build real workflows, real UI, real systems, at a speed that shouldn't be possible. Not because the AI got smarter. Because you gave it enough to be competent. A capsule isn't about the thing. It *is* the thing, completely captured. The implementation is just one possible consequence. --- ## Bounds **Not documentation.** Documentation describes. A capsule briefs. The difference is the same as a city map versus a local showing you around. One gives you information, the other gives you the judgment layer on top. **Not an ontology.** An ontology describes what exists and how things classify. It's a noun: it helps you understand structure. A capsule is a verb dressed as a noun: it describes what something is, what it isn't, and what will trip you up, so you can act without making the mistakes the structure doesn't reveal. An ontology for "Brand" tells you it has sub-entities. A capsule for "Brand" tells you the naming is broken across five systems and there are known data quality issues that will corrupt your results if you don't account for them. **Not a knowledge graph.** A knowledge graph maps relationships between things. A capsule carries the operational context for a single thing, including the things that relationships alone can't tell you. The gotcha that a particular filter includes records it shouldn't? That doesn't live in any graph. It lives in a capsule. **Not a wiki.** Wiki pages are reference material written for completeness. Capsules are operational context written for action. A wiki tells you everything about a topic. A capsule tells you the minimum you need to not screw up. **Not a schema.** A schema describes shape. A capsule describes meaning, bounds, and judgment. A schema tells you that "Brand" has fields. A capsule tells you that "Brand" means three different things in three different systems and the naming is inconsistent. **Not just for engineers, or data, or product.** This is the critical misconception. The first capsules were written in engineering because that's where the pattern was first recognised. But the problem capsules solve (context loss, knowledge fragmentation, confident wrong assumptions) exists in every function. Marketing campaigns have bounds and gotchas. Sales processes have tribal knowledge. Company positioning has explicit "what we are not." Customer segments have hidden context. The primitive is universal. **Not a Claude Skill or a Cursor Rule.** This is the closest comparison, and the one worth taking seriously. Claude Skills and Cursor Rules are genuinely useful. They carry the What, some of the Why, often the How (preferred patterns, conventions). You can share them across a team. You can institutionalise them within Claude for Teams or across a project. They're a near-complete capsule, and that's exactly why the comparison sticks. The gaps are specific. First, they're written for one type of consumer: the AI tool. A human can read a Skill, but it's not written for them. A capsule is written for anyone, human or machine. Second, they're tool-specific. A Cursor Rule only works in Cursor. A Claude Skill only works in Claude. When you move tools, or the next tool arrives, you're rewriting. A capsule is the source that any of them can consume. Third, they almost never carry Bounds or Gotchas. They tell the AI what to do and how. They rarely say what not to do or what will go wrong. That's the gap where mistakes happen. The real relationship: a capsule is upstream, a Skill is downstream. You can generate a Claude Skill from a capsule. You can generate a Cursor Rule from a capsule. You can also generate an onboarding brief, a stakeholder summary, and an API reference from the same capsule. The capsule is the institutional knowledge. The Skill is one compiled output, optimised for one tool. A Skill can't generate a capsule. The direction only goes one way. **Not an AI prompt.** A capsule can be consumed by AI, but it's not written for AI. It's written for anyone who needs to act on a concept without a full briefing from the person who knows it best. The fact that AI can read it is a feature. The fact that a new hire can read it is the same feature. **Not static.** A capsule is a living artefact. It includes lineage (when it was created, when it changed, why) and it gets updated as understanding evolves. A capsule that doesn't reflect current reality is a broken capsule. The structure doesn't prevent staleness, but it makes staleness visible: a Lineage section with a date from eighteen months ago and an Owner who's left the company tells you everything you need to know. A stale wiki page looks the same as a current one. A stale capsule announces itself. --- ## Gotchas **People will anchor capsules to the first domain they see them in.** The data team will see them as a data governance tool. Engineering will see them as a better README. Product will see them as a requirements format. Each of these is true. None of them is the whole picture. The pattern is universal, but adoption stalls when people can't see past their own use case. **"We already do this" is the most common and most wrong objection.** Everyone thinks they already capture context. They don't. They capture description, structure, and sometimes relationships. They almost never capture bounds (what it isn't), gotchas (what will trip you up), or the action surface (how to actually work with it). Ask anyone who says "we already do this" to show you where their documentation says what something is NOT and what will go wrong. The answer is almost always: nowhere. The follow-up objection is usually: "Fine, I'll just add a Gotchas heading to our existing ADR template." That misses the point. An ADR lives in Jira. A PRD lives in Confluence. A README lives in the repo. None of them are portable. A capsule is upstream of all of them. From one capsule you can generate an ADR, a Claude Skill, an onboarding brief, a stakeholder summary, and an API reference. The capsule is the institutional knowledge. Everything else is a compiled output for a specific audience or tool. **The value is in the negative space.** The Bounds and Gotchas sections are where all the differentiation lives. Anyone can write what something is. The hard part, and the part that saves time, prevents mistakes, and makes AI useful, is writing what it isn't and what will go wrong. If a capsule's Bounds and Gotchas are empty, it's just documentation with a new name. **Don't confuse "capsule everything" with "document everything."** Capsuling is not a documentation exercise. It's an act of institutionalising operational context. The difference matters. Documentation is archival: you write it, file it, and hope someone finds it. Capsuling is operational: you write it because someone needs to act on this concept tomorrow and you won't be in the room. You can absolutely set out to capsule your entire business, but the goal is building a queryable, actionable knowledge base, not filling a library. **The "ontology" objection sounds smart but misses the point.** When someone says "this is just ontology," they're seeing the What section and ignoring everything else. Ontologies describe structure so machines can classify. Capsules describe operational context so anyone can act. That's not a subtle difference. It's the difference between a blueprint and a site foreman's briefing. **A capsule is only useful if it's findable.** Writing good capsules is half the problem. The other half is making sure the right capsule surfaces at the right moment. If a company has hundreds of capsules across every team, product, and process, the human or AI acting on a concept needs to find the relevant capsule without already knowing it exists. The naming convention (`{ITEM}_CONTEXT.md`) helps with grep and keyword search. References between capsules help with traversal. But at scale, you also need vector search or tooling that can route a question to the right capsule automatically. A capsule that exists but never gets pulled into the workflow is context that's been captured but still leaks. **Capsules rot too.** Wikis rot because nobody notices. Capsules rot because nobody updates them. The Lineage and Owner sections make staleness visible, but visibility alone doesn't fix it. You need a culture where updating a capsule is part of the work, not a chore after the work. When you change how something operates, you update the capsule. When you discover a new gotcha, you add it. The structure helps, but discipline is still required. Tooling that flags stale capsules or prompts owners for periodic review makes this significantly easier. **Honest gotchas are politically expensive.** A capsule doing its job will say things like "this metric is misleading in these cases" or "this process exists because of a constraint that nobody wants to revisit." That's exactly the context that prevents mistakes, and it's exactly the kind of thing many organisations quietly discourage writing down. If people write the safe version, Bounds and Gotchas become bland and inoffensive, which is the opposite of useful. Capsules need a norm: gotchas are operational risk notes, not blame. Owners are accountable for accuracy, not guilty for the problems they describe. **Perfection kills it.** A capsule with a clear What, one good Bound, and two honest Gotchas is infinitely more valuable than no capsule at all. Start with the thing that burned someone last month. --- ## How ### The Structure Every capsule follows the same pattern, regardless of what it describes: 1. **What** - Purpose, scope, and identity. One paragraph, not a page. 2. **Who** - Who creates this capsule and who consumes it. The authors, the audience, and the handoff pattern. 3. **Why** - The reasoning. The business logic, domain knowledge, the things you'd explain to a smart person who's new to this concept. 4. **Bounds** - What this concept is explicitly not. What's out of scope. What it's commonly confused with. Where the edges are. 5. **Gotchas** - Hidden context. Known landmines. Tribal knowledge. The things that live in someone's head and cause problems when they're not around. 6. **How** - Action pointers. How to interact with, use, query, or build on this concept. Not a manual, a cheat sheet. 7. **Scope** - What this specific capsule covers and what it doesn't. The scope of the document itself, distinct from the bounds of the concept. Plus six meta-sections that sit outside the core: - **Format** - The version of the Context Capsules format this capsule follows. A URL pointing to the canonical definition, e.g. `https://contextcapsules.com/v1/CONTEXT_CAPSULES.md`. Required. This is how a consumer knows what structure to expect, and how tooling knows which version of the format to validate against. - **Sensitivity** - Public, Confidential, or Internal. Public means the capsule can be referenced freely, including by AI agents in external-facing outputs. Confidential means it can be consumed internally but should not appear in outputs shared outside the organisation. Internal means it should only be consumed by people or agents operating within the owning team. Required. This allows consuming agents to filter capsules by sensitivity before acting on them. - **Status** - Draft, Active, or Deprecated. Draft means unvalidated. Active means reviewed and current. Deprecated means kept for reference but no longer acted on. This prevents the most dangerous failure mode: stale context that looks authoritative. - **References** - Other capsules this one relates to or depends on. Makes the connections between capsules explicit so consumers can follow the thread. - **Lineage** - When this capsule was created, when it changed, why. Provenance matters; stale context is dangerous context. - **Owner** - Who's accountable for keeping this capsule current. Capsules don't exist in isolation. As you capsule more of the business, the references between them start to form something that looks like a knowledge graph. But each node carries operational context rather than just a label and a relationship. The graph emerges from the capsules, not the other way around. ### The Format Capsules are written in Markdown. It's human-readable, machine-parseable, works in every tool from VS Code to Notion to a plain text editor, and doesn't lock you into a platform. Every capsule is a single file named `{ITEM}_CONTEXT.md`, where `{ITEM}` is the concept it describes: `BRAND_CONTEXT.md`, `REVENUE_CONTEXT.md`, `ONBOARDING_CONTEXT.md`. The item comes first because that's what people search for. The `_CONTEXT` suffix is what tells you it's a capsule. Sections use standard Markdown headings. Meta-sections (Status, Owner, Lineage, References) sit at the end. References to other capsules use the filename. This keeps the format greppable, version-controllable, and consumable by any AI tool without a custom parser. ### When to Create a Capsule Start where the pain is: - Someone has answered the same question three times. That's a capsule waiting to be written. - A handover is happening. The departing person's head is full of context that will disappear in a week. - An AI tool keeps getting something wrong. The missing context is the capsule you haven't written yet. - A new hire asks a question that takes 45 minutes to answer. That answer is a capsule. - You're about to build something new. Write the capsule first. It forces you to define the What, the Bounds, and the Gotchas before you start, and everything that follows builds on it. ### Where Capsules Apply The same primitive works across every domain: - **A product feature** - what it does, what it doesn't do, what edge cases exist, how to extend it - **A team** - what it's responsible for, what's explicitly not its job, what assumptions people make about it that are wrong - **A metric** - what it measures, what it doesn't measure, what makes it misleading, how to query it correctly - **A customer segment** - who's in it, who's explicitly not, what assumptions will lead you wrong, how to engage them - **A company** - what it does, what it doesn't do, what its positioning explicitly excludes, what internal assumptions need challenging - **A data concept** - what it represents, what it doesn't capture, what known data quality issues exist, how to query it ### Granularity One concept, one capsule. If you're describing the same thing, extend the existing capsule. If you're describing a different thing that happens to share a name, create a new one and make the distinction explicit in both. The test: if two capsules could reasonably be confused with each other, they need to either be merged or their Bounds need to explain the difference. "Brand" as a business concept and "Brand" as a data entity in the warehouse are different things. They get separate capsules (`BRAND_CONTEXT.md` and `BRAND_DATA_CONTEXT.md`), and each references the other. If the capsule count is growing and people can't find what they need, you have a discoverability problem, not a granularity problem. The answer is better indexing and search, not fewer capsules. Every concept has one canonical capsule. If two teams have different understandings of the same concept, that's a conflict that needs resolving, not two capsules. The Owner arbitrates. If genuinely different contexts exist (e.g., "Revenue" means something different in Finance vs. Data), make them separate capsules with explicit cross-references and clear Bounds explaining where each applies. ### The Four Tests A capsule must pass all of them. 1. **If you have to ask a person to use it, it's failing.** A capsule that requires a walkthrough isn't self-service. If a consumer can't pick it up and act, the capsule is incomplete or badly written. 2. **If understanding it requires context from outside, it's incomplete.** A capsule should carry everything a consumer needs to act on the concept. If they have to go find another document, chase down a person, or already know the backstory, the capsule hasn't done its job. 3. **If it contains things that don't belong to it, it's leaking.** A capsule that tries to cover adjacent concepts, implementation details from another domain, or context that belongs in a different capsule is leaking scope. Leaky capsules create confusion and conflict. The Bounds and Scope sections exist to prevent this. 4. **If it doesn't exist and it should, the tax is being paid silently.** Every concept without a capsule is context that lives in someone's head. Every time someone guesses, asks a question that's been answered before, or an AI hallucinates because it lacked bounds, that's the tax. You just can't see the invoice. ### Capsule-First Thinking Write the Bounds first. If you can't say what something isn't, you don't understand it well enough to build anything on top of it. The Bounds section is the forcing function that separates a capsule from a description. For new concepts, write the capsule before you build. Define what it is, what it isn't, and what you already know will be tricky. The capsule becomes the brief that everything else builds on. Every subsequent piece of work, whether it's a feature, a campaign, or an AI integration, iterates on institutionalised knowledge rather than starting from someone's memory. For existing concepts, reverse-engineer the capsule. Sit with the person who holds the knowledge and extract the Bounds and Gotchas. That's where the value is. The What is usually easy. The Bounds and Gotchas are where you discover how much critical context has never been written down. --- ## Scope This capsule defines the concept of Context Capsules. It prescribes a format (Markdown, `{ITEM}_CONTEXT.md`) but does not prescribe specific tooling or enforcement mechanisms. It is domain-agnostic. It applies equally to engineering, data, product, marketing, operations, leadership, and any other function. It does not cover implementation specifics for any particular domain. Those belong in domain-specific capsules. It does not claim capsules are a replacement for documentation, ontologies, knowledge graphs, or schemas. They are a complement: they carry the context those tools consistently fail to capture. --- **Format:** https://contextcapsules.com/v1/CONTEXT_CAPSULES.md **Sensitivity:** Public **Status:** Active **Owner:** Joe Mathews **Updated:** 06 Mar 2026 **References:** None (this is the root capsule) **Licence:** CC BY 4.0 - https://creativecommons.org/licenses/by/4.0/ **Copyright:** Joe Mathews, 2026 **Lineage:** - **May 2025:** Initial concept developed by Joe Mathews. Originally conceived as a logical layer that sits on top of microservices and monoliths to bound the context for AI, allowing it to reason about non AI-native code. The problem: how do you migrate a traditional codebase to an AI-native architecture when the actual implementation doesn't match the desired architecture? The solution combined patterns like facade and strangulation to create logical modular monoliths, crossing the boundary between where the code is and where it needs to be. Context Capsules emerged as the structured context layer that gives AI the bounded knowledge it needs to work with code it wasn't built for. - **Jun 2025:** First introduced to an engineering team. Initial framing around code and API context visibility: AI tools failing due to lack of bounded context, not lack of capability. - **Nov 2025:** Adopted as part of a company-wide AI-native transition of a non AI-native codebase. Formed an integral part of technology vision and platform architecture. - **Jan 2026:** Formal adoption across a wider technology organisation, endorsed as part of data architecture alongside engineering. - **Mar 2026:** This capsule created to define the concept itself in domain-agnostic terms, establishing capsules as a universal business primitive.