s-expr filter discoverability: --where/--filter/query show no example of the common field-equality form

[avrabe]

Friction (dogfooding, hourly loop)

While implementing+using rivet modify --where '<s-expr>' (#380) I reached for the obvious-looking filter (status "draft") and got:

error: invalid --where filter: offset 0: unknown form 'status'
  note: unknown head symbol; see docs/getting-started.md for the supported forms
        (!=/</<=/=/>/>=/and/contains/count/excludes/exists/…/matches/not/or/…)

The error is honest and lists every head form — but for the single most common query an agent writes ("field X equals value Y") it doesn't show the shape. The correct form is (= status "draft") (head is =, not the field name). I only found that by grepping rivet-cli/tests/sexpr_filter_integration.rs.

What finally helped

grep -rE '\(= [^)]+\)' rivet-cli/tests/sexpr_filter_integration.rs → saw (= type "requirement") / (= status "passed") and corrected to (= status "draft").

Suggested fix (small, agent-UX)

1. Add one concrete example to the parse error itself, e.g.:
   note: e.g. (= status "draft"), (and (= type "requirement") (has-tag "safety"))
2. Mirror that example in the --help for the commands that take an s-expr (query, list --filter, export --filter, and now modify --where). The modify --where after_help already includes (and (type "requirement") (status "draft")) — note even that example I first wrote used the wrong (type …)/(status …) shorthand; canonicalizing on (= field "value") everywhere would prevent the same mistake.

This is pure discoverability — the engine itself is fine. It just costs every first-time (human or agent) author one failed round-trip + a grep through tests. Will track the product side as a REQ.

(Filed while landing #380, which adds modify --where.)

[avrabe]

Triage pass — first run on this one (filed 2026-06-02, zero comments). Verified the body against main:

• Parse-error emitter is rivet-core/src/sexpr_eval.rs:797 — the note: lists every head form ((!=, /, >=, and, …) but never shows the (= field "value") shape.
• rivet modify --where after_help (rivet-cli/src/main.rs:990–999) currently advertises two shorthand examples — (and (type "requirement") (status "draft")) and (status "draft") — that, per the issue, would themselves emit the exact failing parse error. Reproduced: the example in the help text is the failing form.
• rivet query, rivet list --filter, and rivet export --filter are the other surfaces that need the canonical (= field "value") example to land consistently.

Sized as one focused PR under "one PR per issue, keep PRs focused": (1) one-line example added to the parse-error note:, (2) canonical (= field "value") form mirrored across the four commands' --help/after_help, including replacing the shorthand examples that today don't parse.

For autonomous pickup, could you add explicit Acceptance Criteria? Shape:

## Acceptance Criteria
- [ ] Parse-error `note:` emitted from `rivet-core/src/sexpr_eval.rs` for `unknown head symbol` includes a canonical equality example, e.g. `note: e.g. (= status "draft"), (and (= type "requirement") (has-tag "safety"))`
- [ ] `rivet query`, `rivet list --filter`, `rivet export --filter`, `rivet modify --where` all show the same `(= field "value")` example in their `--help` / `after_help`
- [ ] The `modify --where` `after_help` shorthand examples (`(and (type "requirement") (status "draft"))`, `(status "draft")`) are replaced with the canonical `(= field "value")` form so every example in the help text parses
- [ ] Regression test: parsing `(status "draft")` emits the parse error AND the error body contains the canonical example string (extend `sexpr_eval.rs` tests around line 2075–2089)
- [ ] `cargo test -p rivet-core` and `cargo test -p rivet-cli` pass; `rivet validate` on the rivet repo still PASS
- [ ] Commit trailer: `Fixes: REQ-NNN` (a new agent-UX/discoverability REQ for the s-expr filter canonical form)

Not implemented this run — also note https://pulseengine.eu/blog/ returned HTTP 503 throughout this run, and the agent's hard-rule says "consult the blog before opening any PR — process posts there are authoritative," so PR work would have been deferred regardless. Pure triage this pass.

---

Generated by Claude Code — issue-triage agent run 2026-06-02.

---

Generated by Claude Code

[avrabe]

Fixed in #383 (REQ-142). The unknown head symbol note now reads:

unknown head symbol — the head is an operator, not a field name. For field equality use `(= "")`, e.g. `(= status "draft")` or `(and (= type "requirement") (has-tag "safety"))`. See docs/getting-started.md for all supported forms (…)

Since the note is generated once in sexpr_eval, it reaches every command that parses a filter — confirmed on both modify --where and list --filter with the exact (status "draft") mistake from this report. Also added an inline example to the export --filter help (it previously had none, unlike list/query, which already showed (= type "requirement")).

[avrabe]

Fixed in #383 (REQ-142) — the s-expr parse error now shows the (= field "value") form across query / list --filter / export --filter / modify --where. Closing.