Seven sections. Every capsule.
The structure doesn't change. The concept does. Every capsule follows the same pattern, regardless of what it describes.
1. What
Purpose, scope, and identity. One paragraph, not a page. If you can't say what this concept is in a few sentences, you don't understand it well enough yet.
2. Who
Who creates this capsule and who consumes it. The authors, the audience, and the handoff pattern.
3. Why
The reasoning. Business logic, domain knowledge, the things you'd explain to a smart person who's new to this concept. The context behind the context.
4. Bounds
What this concept is explicitly not. What's out of scope. What it's commonly confused with. Where the edges are. This is where most of the value lives.
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 keep the capsule alive: Format (versioning), Sensitivity (who can see it), Status (draft, active, or deprecated), Owner (who's accountable), Lineage (when it changed and why), and References (connections to other capsules).
Write the Bounds first.
If you can't say what something isn't, you don't understand it well enough.
The Bounds section is the forcing function that separates a capsule from a description. 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.
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.
For existing concepts, 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.
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 — human or AI — 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 chase down another document, find 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 covering adjacent concepts or implementation details from another domain is leaking scope. 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.
Start where the pain is.
The capsule that matters most is the one for the thing that burned someone last month.
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.
How it works in practice.
You don't write a capsule from scratch. The context already exists — it's scattered across conversations, documents, data definitions, and people's calendars. The work is assembly, not creation.
Pull
Start by pulling context from where it already lives. Slack threads where the concept was debated. Notion docs that partially describe it. The data warehouse definition that the analytics team uses. The meeting where someone explained the edge case. None of these are capsules on their own — but together, they're the raw material.
Assemble
AI is good at this part. Feed it the raw context and ask it to draft the capsule — the What, the Bounds, the Gotchas. It'll get you 70% of the way. The remaining 30% is the judgment layer: the bounds that aren't written anywhere, the gotchas that only the domain expert knows. That's the conversation you have with the person whose head it lives in.
Refine
A capsule gets sharper every time someone works with the concept it describes. After a sprint, a campaign, or an incident — update it. The context is freshest at the point of work. The capsule isn't a document you write once. It's the thing that improves every time someone touches the concept.
Store
A capsule is a Markdown file. It can live in a repo, in Notion, in any tool that handles text. What matters is that it's findable and consumable — by the next person who needs it and by any AI agent that's about to act on the concept.
What you'll encounter.
Capsules work. But they're not magic. Here's what to expect as you scale.
Discoverability.
At 10 capsules, grep works. At 1,000, you need search. The naming convention ({ITEM}_CONTEXT.md) helps. References between capsules help. But at scale, you also need vector search, graph-based linking, or tooling that routes questions 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. This is an active problem — solutions are emerging but not standardised.
Rot.
Capsules go stale like everything else. The difference is the Owner and Lineage sections make staleness visible. But visibility alone doesn't fix it. Updating the capsule needs to be 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.
Perfection.
Don't wait for it. A capsule with a clear What, one good Bound, and two honest Gotchas is infinitely more valuable than no capsule at all.
What this looks like with AI.
The practical workflow above works with or without AI. But capsules were designed to be created with AI assistance — the research, the drafting, the verification. Below is an example skill file that teaches an AI agent how to create a capsule. It connects to your tools, researches the concept, drafts the capsule, checks confidentiality, and verifies against the four tests.
Save this as a file in your AI tool of choice. It references the online spec so the agent always has the current format.
Example: create-context-capsule.md
# Create Context Capsule
You are creating a Context Capsule — a structured operational
briefing for a business concept. This is not documentation.
It's the briefing you'd give someone before they start working
with a concept, carrying the judgment layer that documentation
consistently fails to capture.
Read the full spec before starting:
https://contextcapsules.com/v1/CONTEXT_CAPSULES.md
## Before you start: the confidentiality notice
Context capsules are designed to be shared with any employee.
Before beginning research, tell the user:
> "I'll research this concept using the tools I have access
> to — Notion, Slack, Google Drive, your data warehouse, and
> any other connected sources. The capsule I produce may
> include information drawn from internal conversations,
> documents, and data. I'll flag anything that looks like it
> shouldn't be in a document visible to all employees, but
> please review the final capsule carefully."
Wait for acknowledgement before proceeding.
## The workflow
### 1. Understand the concept
- What concept are they capsuling? A product feature, a team,
a metric, a process, a customer segment, a data entity, a
strategy, the company itself?
- Is the scope right? One concept, one capsule. If the brief
covers multiple distinct concepts, tell the user you'll
create separate capsules and confirm which ones. The test:
if two capsules could reasonably be confused, they need to
either be merged or have Bounds that explain the difference.
- What's the naming? The file will be {ITEM}_CONTEXT.md where
{ITEM} is the concept in UPPER_SNAKE_CASE. For example:
REVENUE_CONTEXT.md, ONBOARDING_CONTEXT.md,
BRAND_DATA_CONTEXT.md.
### 2. Check for existing capsules
Before creating anything, check if this capsule already exists.
Search Notion, check the local filesystem for *_CONTEXT.md
files, search connected sources.
If a capsule already exists for this concept:
- Tell the user what you found
- Ask whether to update the existing capsule or create a new
one with a different scope
- If updating, read the existing capsule first and preserve
its lineage
### 3. Research
Use every available tool to gather context. The goal is to find
operational knowledge — not just what the concept is, but what
it isn't, what trips people up, and what a new person would
need to know to act correctly.
Sources to check (use what's available):
- Notion, Confluence, wikis — pages, docs, meeting notes,
decision records, process docs
- Slack, Teams — threads where the concept was debated,
especially where someone had to explain something repeatedly
(that's a capsule waiting to be written), where something
went wrong, or where confusion surfaced
- Google Drive — documents, spreadsheets, presentations
- Data warehouse — schemas, table structures, known patterns
- Linear, Jira — projects, issues, initiatives
- Existing capsules — for cross-references
Don't try to be exhaustive. Focus especially on:
- Bounds — What is this concept NOT? What's it confused with?
- Gotchas — What trips people up? What tribal knowledge exists?
What assumptions are wrong?
These are the hardest sections to write and where all the value
lives. If you can't find any bounds or gotchas from research,
flag this to the user — they almost certainly exist, they're
just not written down yet.
### 4. Draft the capsule
Follow the exact structure from the spec. Seven core sections:
1. What — Purpose, scope, identity. One paragraph, not a page.
2. Who — Who creates it, who consumes it. The authors, the
audience, and the handoff pattern.
3. Why — The reasoning. Business logic, domain knowledge. What
you'd explain to a smart person who's new to this concept.
4. Bounds — What it is NOT. Out of scope. Commonly confused
with. Where the edges are. This is the most important
section — if Bounds is empty, it's just documentation with
a new name.
5. Gotchas — Hidden context. Known landmines. Tribal knowledge.
The things that cause problems when the person who knows
isn't around.
6. How — Action pointers. How to interact with, use, query, or
build on this concept. A cheat sheet, not a manual.
7. Scope — What this specific capsule covers and what it
doesn't. Distinct from the Bounds of the concept itself.
Plus six meta-sections:
- Format: https://contextcapsules.com/v1/CONTEXT_CAPSULES.md
- Sensitivity: Public, Confidential, or Internal. Ask the user.
Public means freely referenceable including by AI in external
outputs. Confidential means internal consumption only.
Internal means owning team only.
- Status: Draft (always Draft for new capsules — the owner
promotes to Active after review)
- Owner: Ask the user
- Updated: Today's date in DD MMM YYYY format
- References: Related capsules (use filenames)
- Lineage: When created, from what sources
Writing style:
- Write for any reader — human or AI. No jargon without
explanation.
- Bold the lead phrase of each Bound and Gotcha entry.
- Be direct. A capsule briefs; it doesn't hedge.
- Honest gotchas are operationally valuable. Don't sanitise
them — but ensure nothing is included that shouldn't be
visible to all employees.
### 5. Present the draft for feedback
Before saving, show the user:
1. What you're about to create — the concept and filename
2. What you found — a brief summary of your research sources
3. Confidentiality check — flag anything that might be too
sensitive for all-employee visibility. Call out specific
items and ask the user to confirm.
4. Weak spots — if any sections are thin (especially Bounds
and Gotchas), say so. Ask if the user can fill gaps.
5. References — which existing capsules this one references
Wait for approval. Iterate until they're satisfied.
### 6. Verify against the Four Tests
Before saving, run each test explicitly and report results:
1. Self-service — "If you have to ask a person to use it,
it's failing." Can a consumer pick this up and act without
a walkthrough?
2. Self-contained — "If understanding it requires context from
outside, it's incomplete." Does it carry everything needed?
Check for unexplained acronyms, references to processes
that aren't described, assumptions about background.
3. No scope leakage — "If it contains things that don't belong
to it, it's leaking." Does it stay within its declared
scope? Check Bounds and Scope are consistent.
4. Existence justified — "If it doesn't exist and it should,
the tax is being paid silently." Should this actually be
multiple capsules?
Structure check:
- All seven core sections present and non-empty
- All six meta-sections present
- Format URL is correct
- Status is "Draft"
- Owner is specified
- Lineage has at least one entry
- File naming follows {ITEM}_CONTEXT.md convention
- Sections use ## headings
- Horizontal rules between sections
Report results. Don't save until all tests pass.
### 7. Save
Save as {ITEM}_CONTEXT.md. The user moves it to wherever
capsules live in their setup.
## If creating multiple capsules
When the brief covers multiple concepts, create each capsule
separately through the full workflow. For each one:
- Name it correctly
- Research it specifically
- Draft and verify individually
- Cross-reference between related capsules in their References
Tell the user upfront how many capsules you plan to create and
what each will cover. Get confirmation before proceeding.Pick a concept. Open a file.
Write the Bounds.
The full spec has the complete format, examples, and guidance.