Agent cheat sheet

​

The core loop: look → act → observe → assert

Only reticle_act_and_wait and reticle_assert produce a verdict. Everything else moves or reads the app and proves nothing, so a drive ending without one of those two has no result however many tools it used. reticle_act is the tool agents reach for by habit and it catches nothing; act_and_wait is where defects actually surface. And verified: "unknown" is not a pass: it means Reticle drove the app and could not tell what happened. Report it as unknown.

• reticle_act_and_wait({ ref, action }) with no until waits for the page to settle (network + structural DOM idle; ambient count-up/spinner churn is ignored so an animated page still settles) before returning: the one-call replacement for “click then sleep 500ms”.
• Need to wait without acting? reticle_assert({ action: "wait", predicate: { kind: "settled", quietMs } }).
• Waiting for a specific outcome? Pass that consequence as the predicate ({ signal } / { net }), or allOf it with { kind: "settled" } to wait for both the event and the page going quiet.

// Now a real assertion about the field's contents. Before 2.8.0 this passed
// whatever the input held, because `value` was read as a locator operand and,
// with no `by`, silently did nothing.
{ "kind": "element", "role": "textbox", "name": "GST amount", "value": "274.58" }

• You can now assert what a field contains. That was not possible before; agents worked around it by reading the value out of band with reticle_look { action: "find" } and comparing in prose, which produces no verdict and therefore does not count as verification.
• { role, text } now checks the text. It used to match on role alone, so it matched every button on the page. If an assertion you have used for months starts failing, that is the likely reason, and the failure is the truth arriving late.

// WRONG: neither of these parses
{ "allOf": [ … ] }
{ "kind": "allOf", "allOf": [ … ] }

// RIGHT
{ "kind": "allOf", "predicates": [ … ] }
{ "kind": "anyOf", "predicates": [ … ] }
{ "kind": "not",   "predicate":  { … } }

{
  "kind": "allOf",
  "predicates": [
    { "kind": "signal", "name": "auth:granted" },
    { "kind": "net", "method": "POST", "urlContains": "/api/login", "count": 1 },
    { "kind": "console", "level": "error", "absent": true },
  ],
}
// -> evidence: [ { name: "auth:granted", … }, { matched: 1 }, { absent: true } ]

​

The 4-layer cross-check: never trust a green the state contradicts

Rule: a passing UI assert that the store, network, or signal contradicts is a false green.

Store reads (reticle_look { action: "state" }) are the reliable path; the DOM can lie (optimistic UI, stale render).

​

Core tool set

• reticle_verify: the only core tool that CONCLUDES. { action:"crawl" } drives every reachable control itself and reports the whole fault set in one call (destructive: it really clicks). { action:"flows" } replays every saved flow with no model in the loop. Reach for it when you think you are done: every other tool here answers “here is more to look at”.

​

flows vs baselines vs project.json (the persistence layers)

reticle_project / project.json are the run-history layer. flows answer “does the journey still work?”; baselines answer “did the structure change?”; project.json answers “is this run consistent with prior runs?”.

​

Fields worth reading that you may not know are there

​

Start here

0. Just ran reticle init / started the dev server? Poll reticle_session({ action: "list" }) until your tab appears. Readiness is server-internal now, so the first live call already blocks until the SDK connects.
1. reticle_session { action: "list" } finds the connected tab (omit sessionId if there’s only one). An empty list is not a dead end: read the why field. It names which case this is (no app running, an app running that has never dialled this daemon, a project that never went through init, or a tab that closed) and the fix for each. Do not fall back to static reasoning until you have read it.
2. reticle_domain learns the app BEFORE testing: the saved flows, what each asserts, and the gaps (declared signals/testids that no flow verifies, i.e. untested intent). Tells you what to test and where the real risk is without crawling the whole app. Falls back to reticle_capabilities for the raw testable surface (testids, signals, stores, flows).
3. Run the loop: look → act → observe → assert, cross-checking the 4 layers on anything that matters.

​

Token note

• Keep observation cheap. Prefer reticle_look { action: "find" } / scoped or interactive reticle_look { action: "page" } / reticle_assert over dumping the full tree. A full verify loop is ~100 tokens; see token-efficiency.md (~73× leaner than full-tree snapshots).
• Re-look with reticle_look({ action: "page", diff:true }) after an action; it returns only what changed (mode:delta/unchanged), ~99% fewer tokens than a full re-snapshot and no stale tree to mis-read. Every snapshot/query result carries cost:{ bytes, tokens }, so re-scope before reading if it’s large.
• Cap broad reads. reticle_look { action: "find" } takes limit (caps descriptors; reports total/truncated) and count_only (just the match count). reticle_observe { action: "network" } / reticle_observe { action: "console" } take limit (most-recent-N, reports droppedOldest) and carry the same cost hint, so a busy page or wide window never floods your context unnoticed.
• A saved flow tells you if it’s a real test. reticle_flow_save returns assertions.grade (asserted / presence-only / assertion-free); if it’s not asserted, add a consequence (reticle_annotate assert-signal/assert-net or a success-state) so it can’t pass while broken. On replay, an ambiguous heal (two testids tie) is surfaced, never auto-applied. And an apply heal re-replays the rebound flow and refuses to write if the success consequence no longer fires (status:consequence_broken): it heals the locator, never the intent.
• Predicate schema is not bloated. The recursive predicate DSL used by reticle_assert / reticle_assert { action: "wait" } / reticle_act_and_wait is factored, not inlined: when converted to the JSON Schema MCP sends, the predicate body is emitted once (~2.7k chars ≈ ~685 tokens per tool) and recursion is handled by self-$ref (#/properties/predicate), with no per-recursion duplication. No action needed.
• One tool surface, and a hatch behind it. Reticle advertises navigate/act/act_and_wait/assert/look/observe/session/verify, plus reticle_tools and reticle_run. That is the whole detect loop, the file-pointer, the feedback channel, the handback, and the one tool that CONCLUDES, reached by an action argument rather than by a name each. reticle_tools discovers: no args lists every registered tool name and summary, names:[…] loads full params on demand. reticle_run { tool, args } then calls any of them, advertised or not, which is what keeps recording a flow, screenshots, visual diff, storage, network mocking and the clock reachable without spending a slot on each. A daemon started with RETICLE_ADVERTISE_ALL_TOOLS=1 (read at startup, so restart it) advertises the full table outright, with output schemas. reticle_verify is advertised: { action:"flows" } replays every saved flow with no model in the loop, and { action:"crawl" } drives every reachable control itself and reports the whole fault set in one call. Sizes are deliberately not quoted here. A count in prose goes stale, and has three times already. reticle_tools reports the live surface, and SKILL.md carries the one gated table.