HEDDLE

Guide

Annotating for the next agent

Context annotations attach reasoning to specific files, symbols, or line ranges. When the next agent opens the file, the active contexts are right there, and context check tells you when the code has drifted out from under them. 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 src/auth/mod.rs (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, the rationale stops applying, the invariant gets relaxed. Staleness is checked on demand: context check compares each annotation against the current source and flags the ones whose target moved or vanished. The reasons are source_changed, symbol_missing, and file_missing.

Check annotations against the current code

bash$ heddle context check  ✗ src/auth/mod.rs  symbol:authorize  source_changed  ✗ src/oplog/mod.rs  symbol:append  symbol_missing12 annotations checked: 10 fresh, 2 stale, 0 unknown

For a repo-wide roll-up rather than a per-target list, use context audit. It reports the totals across every annotated target, including superseded and duplicate annotations alongside the stale count:

Summarize the annotation graph

bash$ heddle context auditannotations: 12superseded: 1duplicates: 0stale: 2

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