intent-capsule

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)