HEDDLE

Guide

Reviewing a task

A reviewer's day. Read the resolved state, see what questions are still open, ask one of your own if needed, sign the result with the right kind (human read, agent preview, agent co-review), move on to the next one.

1. Read the resolved state

heddle review show renders the review payload for a state, by default the current HEAD. You'll see the headline, the agent narrative if one exists, in-budget signals (novelty, test reachability, pattern deviation, invariant adjacency, self-flagged uncertainty), any discussions on the symbol set, and any signatures already attached.

Read the review payload for the current state

bash$ heddle review showreview of state hd-d7k3m9qr2x4n  replace JWT auth with Biscuit capabilities  agent narrative:    Dropped the JWT compat shim after the first capture; the    second path lands clean. Tests green on the new verifier.  signals (in budget):    novelty · 0.42    test_reachability · 0.91  signatures: (none)  available signing kinds: read, agent-preview, agent-co-review

Pass --all-signals to see signals outside the default budget. Pass a specific state ID as a positional to review a state other than HEAD: heddle review show hd-9cz4p2tn6kqr.

2. Ask a question, if needed

If something on the diff makes you pause, open a discussion anchored to the symbol in question. Discussions are first-class objects on the state: the resolver sees them, later reviewers see them, future agents inherit them.

Open a discussion on a function

bash$ heddle discuss open src/auth/mod.rs authorize "should this short-circuit on scope mismatch?"discussion dsc-2qpsr7  anchor: src/auth/mod.rs:authorize  state: hd-d7k3m9qr2x4n  visibility: internal  status: open

3. Sign the state

Signing is over the resolved state, not over the captures inside the thread. Three signing kinds distinguish what kind of attestation this is:

  • read: a human reviewed it.
  • agent-preview: an agent looked but didn't co-sign.
  • agent-co-review: a second agent (typically a different model) co-signed the resolved state.

heddle review sign is the low-level command. It takes the signature bytes prepared by your editor integration, your heddle agent daemon, or a CI step. The bare invocation looks like:

Sign as a human read

bash$ heddle review sign hd-d7k3m9qr2x4n --kind read --public-key <hex> --signature <hex> --signed-at-unix 1715472851signed state hd-d7k3m9qr2x4n as read (signature_id sig-9a2f)

4. Move on to the next review

heddle review next walks to the next pending review reachable from HEAD. Pass --mine-only to filter to states queued specifically for you.

Walk to the next pending review

bash$ heddle review next --mine-onlynext pending review: hd-e3a7c9bktwnv  add scope-narrowing tests  existing signatures: 1

Or "no pending reviews in the last 50 states reachable from HEAD" if you're caught up.

A note on signal health

Over time, you'll want to know whether your review signals are firing too often, too rarely, or about right. heddle review health reports per-module fire rates over a rolling window of states. Pass --window N to set the window explicitly; with no flag, the server picks a sensible default.

Per-module signal health

bash$ heddle review health --window 50signal health (window: 50 states)  novelty                          12.0%  test_reachability                 6.0%  pattern_deviation                28.0% ⚠  invariant_adjacency               4.0%  self_flagged_uncertainty         18.0%

Next