Reticle Docs: verification for AI coding agents

Each recipe is a situation, the call that verifies it, and what came back. Every response on this page was captured from a running app on 2026-08-16. Refs like e605 are session-specific: take your own from reticle_look { action: "find" } before copying a call. One call, three conditions. The signal fired, exactly one request went out, and nothing was logged.

{
  "ref": "e605",
  "action": "click",
  "until": {
    "kind": "allOf",
    "predicates": [
      { "kind": "signal", "name": "auth:granted" },
      { "kind": "net", "method": "POST", "urlContains": "/api/login", "count": 1 },
      { "kind": "console", "level": "error", "absent": true }
    ]
  }
}

{
  "verified": "yes",
  "because": "assertion held at signal grade over a clean capture with no channel disagreeing",
  "verdict": {
    "pass": true,
    "evidence": [
      { "name": "auth:granted", "data": { "email": "admin@reticle.dev" } },
      { "matched": 1 },
      { "absent": true }
    ]
  },
  "summary": {
    "stateDiffs": [{ "path": "auth", "from": null, "to": "{…}" }],
    "storageKeysChanged": ["reticle.bench.authToken", "reticle.bench.sessionId"]
  },
  "honesty": { "grade": "signal", "coverage": { "pct": 100, "partial": false } }
}

Each child predicate reports its own evidence, in order. count: 1 is the part that catches double-submit, and it costs nothing to ask for.

”Did navigating actually change the view?”

{ "ref": "e618", "action": "click", "until": { "kind": "signal", "name": "nav:changed" } }

{
  "verified": "yes",
  "verdict": {
    "pass": true,
    "evidence": { "name": "nav:changed", "data": { "view": "deployments" } }
  },
  "summary": {
    "statePathsChanged": ["app"],
    "stateDiffs": [{ "path": "view", "from": "overview", "to": "deployments", "atMs": 49084 }],
    "signals": ["nav:changed"]
  },
  "honesty": { "grade": "signal", "coverage": { "pct": 100, "partial": false } }
}

The signal carries the destination in its payload, so one predicate proves both that navigation happened and that it went to the right place. Here is a real failure, kept because it teaches more than another pass.

{
  "ref": "e623",
  "action": "click",
  "args": { "confirmDangerous": true },
  "until": {
    "kind": "allOf",
    "predicates": [
      { "kind": "element", "query": { "role": "dialog" }, "state": "visible" },
      { "kind": "console", "level": "error", "absent": true }
    ]
  }
}

{
  "verified": "no",
  "verdict": {
    "pass": false,
    "evidence": [
      {
        "pass": false,
        "expected": "an element matching {\"role\":\"dialog\"} in state 'visible'",
        "observed": "no matching element on the page",
        "assertion": "element.present",
        "evidence": {
          "presentTestids": ["deploy-table", "filter-search", "env-filter", "sign-out", "…"]
        }
      },
      { "pass": true, "evidence": { "absent": true } }
    ]
  },
  "summary": {
    "stateDiffs": [{ "path": "newDeployOpen", "from": false, "to": true, "atMs": 60862 }],
    "signals": ["modal:opened"]
  },
  "capsule": { "blastRadius": ["state app", "signal modal:opened"], "firstDivergence": null }
}

Read the summary. The modal did open. newDeployOpen went false to true and the app fired modal:opened. capsule.blastRadius says the same thing as a list: the click moved the app store and fired modal:opened, and nothing else. The assertion was wrong, not the app. That modal is a div with no role="dialog", so a role query could never match it. (Which is also an accessibility bug worth fixing, found for free.) The right predicate was sitting in the response the whole time:

{ "until": { "kind": "signal", "name": "modal:opened" } }

When an assertion fails, read summary.signals and summary.stateDiffs before you assume the feature is broken. They tell you what actually happened, and usually hand you the predicate you should have written.

”Nothing matched, and I do not know why”

An empty reticle_look { action: "find" } result tells you what is there:

{
  "count": 0,
  "elements": [],
  "hint": {
    "route": "/hostile",
    "knownEmptyState": true,
    "presentTestids": ["nav-overview", "nav-deployments", "hostile-view", "hostile-ticker", "…"],
    "presentRegions": [{ "role": "list", "childCount": 0, "name": "hostile-feed", "sample": [] }]
  },
  "cost": { "bytes": 402, "tokens": 101 }
}

The testid existed, on another route. hint.route says where you actually are and presentTestids says what is here instead, for 101 tokens and no snapshot. presentRegions is the other half: a list with childCount: 0 is an empty state, which is a different bug from a list that failed to render at all.

”Is this button destructive?”

Reticle refuses controls that look destructive, before acting:

{
  "error": "potentially destructive action blocked; retry with args.confirmDangerous=true",
  "recovery": "Reticle blocked a control whose label reads as consequential (delete, remove, revoke, pay…) on purpose. If you mean it, send the SAME call again with `args: { confirmDangerous: true }`: it goes inside the `args` object, not beside it. This is a deliberate refusal, not a defect: there is nothing to report."
}

Confirm it explicitly when you mean it:

{ "ref": "e623", "action": "click", "args": { "confirmDangerous": true }, "until": { … } }

The matcher reads the control’s label. It stops a control whose words destroy something (delete, remove, revoke, reset…) or move money (pay, buy, transfer, refund…). It can stop a harmless control that uses one of those words, for example “Remove filter”. That is the trade: a false stop costs you one argument, and a false start costs you a deleted record.

”Did my change break anything else?”

{ "tool": "reticle_verify", "args": { "action": "change", "since": "HEAD~1" } }

Give it the files you edited, or a git ref. It works out which saved flows cover them and replays only those.

”What is even testable in this app?”

The best first call on an unfamiliar codebase:

{ "tool": "reticle_capabilities" }

{
  "testids": ["login-email", "login-submit", "new-deploy", "deploy-submit", "…"],
  "signals": ["auth:granted", "auth:denied", "deploy:created", "modal:opened", "…"],
  "stores": ["app"],
  "flows": [
    {
      "name": "ship-a-deploy",
      "steps": ["nav-deployments", "new-deploy", "deploy-name", "deploy-submit"]
    }
  ],
  "source": "live"
}

That is the app stating what it considers testable, which beats snapshotting the DOM and inferring it from element names.

”The error state has never been tested”

Most error states have never run. Force one:

{
  "tool": "reticle_network_mock",
  "args": { "mocks": [{ "urlContains": "/api/deploys", "status": 500 }] }
}

Then drive the flow and assert the error UI appears. Pass clear: true to turn mocking off.

This one needs a browser that Reticle controls: a leased tab (reticle_lease) or a driven browser (reticle drive <url>, or RETICLE_CDP_URL). Mocks go through CDP, and the always-on SDK in your own tab cannot apply them. Against your own tab the call returns

{
  "applied": false,
  "count": 0,
  "ok": false,
  "reason": "no-cdp-provider",
  "recommendation": "this needs a Reticle-driven browser (it is applied through CDP, which the always-on SDK cannot do), start with `reticle drive <url>` or set RETICLE_CDP_URL"
}

On a lease or a driven browser the same call answers { "applied": true, "count": 1 }. reticle_viewport follows the same rule and also reports no-cdp-provider against your own tab. reticle_screenshot and reticle_visual_diff also work on a lease or a driven browser, and report no-visual-provider against your own tab.

”I want this to run on every PR”

Record it once, replay it forever:

{ "tool": "reticle_verify", "args": { "action": "flows", "names": ["docs-check"] } }

Omit names to replay every saved flow. Either way you get one consolidated verdict, and only the failures carry detail:

{
  "status": "fail",
  "total": 1,
  "passed": 0,
  "failed": 1,
  "summary": "0/1 flows pass, 1 need attention: docs-check",
  "failures": [
    {
      "flow": "docs-check",
      "verdict": "drift",
      "whatChanged": "testid \"login-submit\" not found",
      "whereInSource": "src/components/Login.tsx:81",
      "nextAction": "rebind the anchor to \"sign-out\" (closest survivor), or update the flow if the change was intended."
    }
  ]
}

It also returns flaky, the flows it has seen both pass and fail on unchanged code. Treat that list as a bug in the flow, not in the app.

The predicate grammar

Every kind, every field, and which ones actually prove something.

Best practices

The habits behind these recipes, and the mistakes that produce a confident wrong pass.

Tools

Beyond the loop

CLI commands

Packages

Grammar

Long form

Recipes: copy, paste, verify

”Did navigating actually change the view?”

”Nothing matched, and I do not know why”

”Is this button destructive?”

”Did my change break anything else?”

”What is even testable in this app?”

”The error state has never been tested”

”I want this to run on every PR”

The predicate grammar

Best practices

​”Did the login actually work?”

​”Did navigating actually change the view?”

​”Did the modal open?” and the lesson in getting it wrong

​”Nothing matched, and I do not know why”

​”Is this button destructive?”

​”Did my change break anything else?”

​”What is even testable in this app?”

​”The error state has never been tested”

​”I want this to run on every PR”

The predicate grammar

Best practices

”Did the login actually work?”

”Did navigating actually change the view?”

”Did the modal open?” and the lesson in getting it wrong

”Nothing matched, and I do not know why”

”Is this button destructive?”

”Did my change break anything else?”

”What is even testable in this app?”

”The error state has never been tested”

”I want this to run on every PR”