# 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. There is a second-order point worth being explicit about. A capsule that reads as complete and a capsule that produces complete outputs when consumed are not the same thing. The abstract sections (What, Why, Bounds, Gotchas) survive a read-through. The concrete sections (Example, Calibration, Acceptance) survive an implementation attempt. A capsule with only the first kind is half-deployed. It has been written, but not yet operationally proven. The new sections in v2 of this format exist to close that gap. 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 abstract-only.** A capsule that contains only What, Why, Bounds, Gotchas, How, and Scope is a half-capsule. It tells the consumer what to think about, but leaves every concrete decision to interpretation. Two consumers reading the same abstract-only capsule will produce different outputs, scattered across whatever the Bounds permit. The concrete sections (Example, Calibration, Acceptance, and Interface when applicable) anchor those outputs to a single point. Without them, the capsule passes a read-through but fails when a consumer tries to act, and the failure is usually invisible until the divergent outputs collide with each other downstream. **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. **Abstract-only capsules look complete but fail at re-implementation.** A capsule with strong Bounds and Gotchas but no Example, Calibration, or Acceptance will guide a consumer through the major pitfalls and then force them to guess every concrete decision: which value, which threshold, which interface shape, which output shape. The guesses are usually wrong by enough to matter, and the failures are silent because the consumer can't tell their interpretation from yours. This trap is particularly bad with AI consumers: an LLM reading an abstract-only capsule will produce something plausibly-shaped and confidently wrong on every unspecified numeric. Example, Calibration, and Acceptance close those gaps. They are the smallest set of additions that take a capsule from "intent specified" to "implementation reproducible." **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. **Example** - One concrete worked instance. Real values, real inputs, real outputs. The grounding case the abstract sections describe. 8. **Calibration** - The actual values and parameters used in the canonical instance of this concept today. Not the working range, the operating point. 9. **Interface** - For executable capsules only. The minimum contract any implementation must honour. Function signatures, persisted artefact shapes, API surface. 10. **Acceptance** - What working correctly looks like at the output level. Concrete positive criteria that a consumer can verify against. 11. **Scope** - What this specific capsule covers and what it doesn't. The scope of the document itself, distinct from the bounds of the concept. Sections 1 through 8, plus 10 and 11, are required for every capsule. Section 9 (Interface) is required only when the capsule describes an executable concept such as an algorithm, a service, a pipeline, or a data product. Add it when present, omit when not applicable. 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/v2/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 Concrete Sections The four concrete sections (Example, Calibration, Interface, Acceptance) deserve a closer look because they are the additions in v2 of this format and the easiest to get wrong. **Example.** One concrete worked instance of the concept, fully grounded. Not the abstract definition from What. A specific case with real values, real inputs, real outputs. For a metric capsule, a real time period with the actual numbers. For a customer segment capsule, a specific representative customer with their actual context. For a process capsule, one historical run with the inputs that came in and the outputs that went out. For an algorithm capsule, one input, one output, and the observable markers that demonstrate the algorithm worked. The Example is the falsifiability check on the abstract sections. If you cannot describe one concrete instance of the concept in a short paragraph with specific values, your capsule is either describing a category rather than a thing, or you don't have a clear grip on the concept yet. Either is fixable; both are visible only when you try to write the Example. **Calibration.** The actual values, thresholds, parameters, and defaults used in the canonical instance of this concept today. Not ranges, not "approximately." The values you operate at. Bounds says where the working zone is. Calibration says where in that zone you actually live. The distinction matters: "the working band is 0.6 to 0.9" tells a re-implementer the safe range; "we currently run at 0.8" tells them where to start. For an algorithm, the hyperparameters used in production. For a metric, the thresholds for green, yellow, red. For a customer segment, the actual sizing, the current churn rate, the typical deal size. For a process, the cadences, the SLAs, the actual durations. A capsule with Bounds but no Calibration tells you what to avoid and leaves you guessing about where to commit. **Interface.** For executable capsules only. The minimum contract that any implementation must satisfy. Function signatures, persisted artefact shapes, expected I/O. Not the implementation itself. The shape downstream consumers rely on. Two engineers implementing the same capsule should produce code that is API-compatible at the level Interface specifies, even if their internals differ. Interface differs from How: How is the cheat sheet for the algorithm or process. Interface is the contract the implementation must honour for downstream code to keep working. **Acceptance.** What working correctly looks like at the output level. Concrete positive criteria, not just the absence of the failure modes listed in Gotchas. For a metric, a healthy value, an unhealthy value, and what to look at when it drifts. For an algorithm, a sample output and the observable markers that demonstrate the algorithm did what it was supposed to. For a process, what a good completion looks like. For a customer segment, signs that someone is or isn't a member. Bounds and Gotchas are the negative space: what the concept isn't, what fails. Acceptance is the positive space: what success looks like in the wild. Without Acceptance, a consumer knows what to avoid but cannot tell when they have succeeded, and they end up over-relying on absence-of-failure as a proxy for success. A useful pattern: write Acceptance as something you could turn into a check. "When parameter X is in the working band, the output contains markers A, B, C while preserving constraints D, E." That formulation is reusable. A human can verify it, an AI can verify it, automated tests can verify it. Acceptance written this way becomes the contract between the capsule and reality. ### 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, the Gotchas, and the Acceptance 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. The Example, Calibration, and Acceptance sections exist specifically to harden the first two tests. A capsule can pass them on a human read-through and still fail them when a consumer (especially an AI) tries to act, because abstract sections leave concrete decisions to interpretation. Concrete sections close that gap. ### 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. Write the Example next. If you can't describe one concrete instance of the concept with real values, you don't have a thing yet, you have a category. The Example is the forcing function that separates a thing from an idea. For new concepts, write the capsule before you build. Define what it is, what it isn't, what you already know will be tricky, what success looks like, and what your starting numbers are. 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, the Gotchas, the Calibration, and the Acceptance criteria. That's where the value is. The What is usually easy. The Bounds, the Gotchas, the actual numbers in current use, and the markers of success are where you discover how much critical context has never been written down. --- ## Example A worked instance of this format applied to itself. A v2 Context Capsule for "Quarterly Customer Health Review" would have: - **What**: a structured review of every named customer's account health, run once per quarter by the Customer Success team. - **Why**: surfacing churn risk early so account managers can intervene before renewal conversations. - **Bounds**: not a NPS report, not a billing review, not a product feedback channel. - **Gotchas**: usage numbers are misleading for accounts mid-migration; the "active users" definition changed in Q1 2026 and pre-Q1 data is not comparable; one customer (Acme Corp) has a custom contract that breaks the standard scoring rubric. - **How**: pull the health dashboard, run the standard scoring rubric, flag red and amber accounts to the AM channel. - **Example**: in Q1 2026, 47 accounts reviewed, 6 flagged red, 2 flagged amber. Red accounts received a 30-minute intervention call within 14 days. Of the 6 red flags, 4 renewed, 1 churned (anticipated), 1 expanded. - **Calibration**: red threshold is health score below 40, amber is 40 to 60, green is 60 plus. Review window is the first two weeks of each quarter. Average review takes 90 minutes per account. - **Acceptance**: a good review produces a flagged list with named owners, scheduled intervention dates within 14 days for every red, and updated notes in the CRM. A bad review produces a list with no owners or no follow-up dates. - **Scope**: covers the review process. Does not cover the construction of the health score itself (see `HEALTH_SCORE_CONTEXT.md`) or the intervention playbooks (see `CHURN_PLAYBOOK_CONTEXT.md`). The abstract sections (What, Why, Bounds, Gotchas) tell a consumer what the review is and what to watch for. The concrete sections (Example, Calibration, Acceptance) tell them what the review looks like when it runs, what numbers to use, and how to know they have done it correctly. A new Customer Success hire can run a Q4 2026 review from this capsule alone. --- ## Calibration The values this format itself currently operates at. The ranges below are diagnostics, not hard limits: a count or length outside a range is a prompt to look closer, never a licence to pad and never a mandate to cut real content. - **Required sections**: 10 of 11 (Interface is conditional). All other sections required, including the four concrete sections added in v2. - **Meta-sections**: 6, all required. - **File naming**: `{ITEM}_CONTEXT.md`. Uppercase concept name, underscore-separated. Always ends in `_CONTEXT.md`. - **Length target**: 200 to 400 lines for most capsules. Under 100 lines usually means a missing Gotcha or two; over 600 usually means leaking scope, and points to splitting the capsule rather than trimming real content. Optimise for signal density — the minimum a consumer needs to act — not for a line count. - **Bounds entry count**: typically 5 to 10. Fewer than 3 is suspicious: the negative space is under-explored. A higher count is not a ceiling but a trigger — keep every load-bearing Bound, and use the count to check whether the capsule is leaking scope (two concepts that should be split) or padding with low-signal entries. - **Gotcha entry count**: typically 5 to 10. Fewer than 3 is suspicious: the tribal knowledge has not been mined. The upper end is the same trigger as for Bounds — never drop a real landmine to hit a number; a high count instead asks whether the concept should be split or the entries curated for signal. - **Review cadence**: capsules with `Status: Active` should have a `Lineage` entry no older than 12 months. Capsules with no update in 18 months should be flagged for re-review or moved to `Status: Deprecated`. - **Reference target**: most capsules link to between 1 and 5 other capsules. Zero references is a sign the capsule is isolated; more than 10 is a sign it is doing too much. --- ## Acceptance A capsule is working correctly when: - A consumer who has never seen the concept before can act on it without asking the Owner a clarifying question. - An AI agent given only the capsule and a task on the concept produces work that the Owner would accept without rework on the concrete decisions (the values used, the interface shape, the success criteria). Stylistic and structural choices may still vary; the substantive ones should not. - Two independent implementers producing work from the same capsule arrive at outputs that are compatible at the Interface level (when applicable) and matching at the Calibration level. - The Lineage shows recent activity, the Owner is current, the Status is honest. - The Bounds and Gotchas sections each contain at least three substantive entries, none of which are bland. - The Example references concrete values, not placeholders. - The Acceptance section itself contains criteria a reader could turn into a check. A capsule is failing when: - Consumers regularly DM the Owner to clarify what the capsule means. - Two implementers reading the same capsule produce outputs that diverge on values, thresholds, or interface decisions. - The Bounds section contains generic statements ("Not a full implementation guide") rather than specific exclusions. - The Example is missing, abstract, or uses placeholder values like "X" and "Y." - The Calibration section is missing or hedged with "approximately" everywhere. - The Lineage has not been updated in a year and the Owner has left the company. --- ## Scope This capsule defines the concept of Context Capsules, version 2 of the format. It prescribes a format (Markdown, `{ITEM}_CONTEXT.md`, eleven sections plus six meta-sections) 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. v2 differs from v1 by adding four sections (Example, Calibration, Interface, Acceptance) to address the gap between "capsule is intelligible" and "capsule is reimplementable." v1 capsules remain valid; tooling that validates against v1 will accept v1 capsules. A v1 capsule can be upgraded to v2 by adding the four concrete sections and changing the `Format` URL. --- **Format:** https://contextcapsules.com/v2/CONTEXT_CAPSULES.md **Sensitivity:** Public **Status:** Active **Owner:** Joe Mathews **Updated:** 30 May 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:** v1 of the format published. This capsule created to define the concept in domain-agnostic terms, establishing capsules as a universal business primitive. - **May 2026:** v2 of the format. Added four concrete sections (Example, Calibration, Interface, Acceptance) after empirical implementation feedback. A v1 capsule could survive a human read-through and still fail when consumed by an AI implementer, because the abstract sections left every concrete decision (values, thresholds, interface shapes, success criteria) to interpretation. Surfaced during a brand-voice steering implementation: the v1 capsules guided the reimplementation through the major pitfalls and forced guesses on every hyperparameter, function signature, and acceptance criterion. v2 closes that gap by making the concrete grounding part of the core structure rather than something a careful author might think to include. - **May 2026:** Clarified the Calibration heuristics — the Bounds, Gotchas, and length ranges are diagnostic triggers, not hard caps. A high count or long capsule prompts a scope-leak/split or curation check; a real Bound or Gotcha is never dropped to hit a number. Wording only — no change to the format's structure, so existing v2 capsules remain conformant.