intent-capsule
Capture work intent at peak context, encode it in a terse convention an LLM already understands, and replay it cold in a later (or different) context-poor session — without the silent omissions that kill handoffs.
One line: catch your smartest moment in a bottle so a forgetful (or brand-new) executor can finish the job right.
The problem
The best understanding of any piece of work exists at one moment: peak context, in the head of whoever is deep in it. That understanding then dies two ways:
- It rots — you come back next week and you've forgotten which detail was load-bearing.
- It can't travel — someone else (or a fresh AI session after a
/clear) has to do it and can't read your mind.
A normal note doesn't fix this, because people told to "be brief" silently drop the two things that matter most: where the work goes and what done looks like.
The idea
A capsule is a note with labeled boxes you're not allowed to leave blank. It's written in a terse shorthand of words/symbols the model already knows (in-distribution — a brand-new symbol language was tested and hurts comprehension), and the legend is taught once in a cached prefix so the teaching cost is paid at a ~90% discount.
@<id> do: <one-line: what to build> in: <files/layer> needs: <capsule-ids> group: <label> on: <provenance>
!: <hard constraint> ~: <soft pref> ?: <gate> =: <acceptance> why: <the nuance>
- Required:
id, do, and at least one = (acceptance). The queue rejects a capsule missing these — at capture, while context is fresh and the gap is cheap to fix.
- Recommended:
in, why.
- Repeatable:
!, ~, = (one rule/criterion per line). Single: do, in, on, needs, group, ?, why.
Fields
| Field | Role | Notes |
|---|
do: | What to build (required) | One line. |
in: | Files or layer the work lives in | Recommended. |
needs: | Space/comma-separated capsule ids this capsule depends on | Gates surfacing — a capsule stays hidden in next/pickup until all its needs: ids are done. |
group: | Organizational label | pickup prints a per-group progress rollup, e.g. shipsafe — 4/10 done (2 ready, 4 blocked). |
on: | Provenance prose | Context the executor needs ("what to know before starting"). Not gated — does not block surfacing. |
!: | Hard constraint | Repeatable. |
~: | Soft preference | Repeatable. |
?: | Gate/prerequisite question | |
=: | Acceptance criterion | Repeatable (required ≥ 1). Attested one-for-one by done --proof. |
why: | The nuance | Recommended — load-bearing context that prose drops. |
See examples/example-capsule.txt for a full one.
Why it works (measured, not vibes)
Two regimes, one mechanism — depends on whether the intent is simple or rich (full method + stats in RESULTS.md):
| Intent type | Convention vs plain English | Tokens | Why use it |
|---|
| Simple plan-ops | 95.0% vs 96.7% fidelity — statistical parity (p=0.69) | ~64% fewer | compression |
| Rich implementation | 10.0/10 vs 9.67, won head-to-head 3–0 (9 ties) | ~40% more | completeness |
For rich intent the convention costs more tokens — and that's the point. Terse prose's weak dimensions were exactly where (1.83/2) and acceptance (1.83/2); the labeled fields are a checklist that refuses those omissions. Proof point: one of these capsules was authored at peak context and built correctly by a later "stranger" session that had zero memory of writing it.
The instinct is "shorthand = save tokens." For rich intent that's wrong — prose is shorter. The win is completeness. Lead with that.
The honest caveat (don't skip)