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-d01a8b4e  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-9c41.

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 "fn authorize" "should this short-circuit on scope mismatch?"discussion dsc-2qpsr7  anchor: src/auth/mod.rs:fn authorize  state: hd-d01a8b4e  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-d01a8b4e --kind read --public-key <hex> --signature <hex> --signed-at-unix 1715472851signed state hd-d01a8b4e 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-e3a7c1b9  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