HEDDLE

Guide

Annotating for the next agent

Context annotations attach reasoning to specific files, symbols, or line ranges — and travel with the code through refactor. When the next agent opens the file, the active contexts are right there. This guide walks the operations you'll actually do: attach, read, audit, evolve.

What an annotation looks like

A context annotation has a target (a file, with an optional scope inside the file), a kind, and a body. The CLI shape is:

  • --path <path> XOR --state <state> — what the annotation attaches to.
  • --scope file (default) | symbol:<name> | lines:<start>-<end> — narrower targeting within the file.
  • --kind <kind> — one of rationale (default), invariant, constraint.
  • -m <text> or --file <path> — the annotation body.

See heddle context for the full surface (10 subcommands).

1. Attach an annotation

Attach a rationale to a function

bash$ heddle context set --path src/auth/mod.rs --scope symbol:authorize -m "scope check happens before role check by design"Annotated fn authorize (1 active annotation)

No --kind here — that defaults to rationale. For other kinds, pass --kind invariant (must always hold) or --kind constraint (external requirement, often references a ticket or standard).

2. Read what's active

heddle context get resolves the active annotations at a target. The output is multi-line — one block per annotation, with the kind, the logical annotation ID, the status, the author, and the body.

Read all annotations on a file

bash$ heddle context get --path src/auth/mod.rsfile src/auth/mod.rs--- [rationale] ann-9a2f (active) ---by: anan@heddle.shscope check happens before role check by design--- [invariant] ann-9b04 (active) ---by: anan@heddle.shcapability chain must be append-only

Filter by scope, tag, or historical state with the corresponding flags. --tag is useful once you've started tagging annotations for cross-cutting grouping (e.g. --tag security).

3. Evolve an annotation

Annotations have logical IDs that persist across revisions. heddle context edit adds a revision to an existing annotation; heddle context supersede creates a replacement annotation and marks the previous one superseded; heddle context history walks the revision chain.

Revise an existing annotation

bash$ heddle context edit ann-9a2f -m "scope check before role check — Biscuit verifier handles both"Revised annotation ann-9a2f

Use supersede when the new note is materially different (more than a rewording). Heddle reports the rewrite percentage so an auditor can see how big the change was:

Replace an annotation with a different framing

bash$ heddle context supersede ann-9a2f --path src/auth/mod.rs --scope symbol:authorize --kind rationale -m "ordering is enforced by the Biscuit verifier; the legacy comment about scope-first is now misleading"Superseded annotation ann-9a2f with a 72% rewrite

4. Audit what's stale

Over time, annotations drift — the code they describe changes more than re-anchoring can track, the rationale stops applying, the invariant gets relaxed. Heddle's context check and context audit surface the problems.

Find stale annotations across the repo

bash$ heddle context audit12 active annotations, 2 flagged:  ann-7c12 [rationale] src/auth/mod.rs:fn authorize — target moved 3 times since last edit  ann-3e0a [invariant] src/oplog/mod.rs:fn append — claim mentions "BLAKE2" but code uses BLAKE3

Pair with heddle context suggest on the opposite end — symbols that are getting modified often and don't have any annotations. The two surfaces together keep the annotation graph honest.

5. The next agent inherits

When an agent opens a file — through an IDE integration or via heddle agent capture — Heddle surfaces the active annotations automatically. No wiki to read, no chat history to scroll. The reasoning is right next to the code.

Concretely: as a workflow, after you make a non-obvious decision, take 30 seconds and annotate the symbol that encodes it. The cost is one CLI command; the payoff is every agent and reviewer that touches that symbol later sees the reasoning without asking.

Next