reticlehq/reticle

replay-user-flows

Turn a user journey you just clicked through into a saved regression check that re-runs deterministically, with no model in the loop and no test code to write.

Quelltext ansehen

Verwendung

  1. Installationsbefehl kopieren und das Quellpaket vor der Installation in der eigenen Agentenumgebung prüfen.
  2. Benötigte Werkzeuge, Zugangsdaten und Hosts im Original prüfen.
  3. Eingabe und gewünschtes Ergebnis beschreiben und die Ausgabe mit den Quellen abgleichen.
npx skills add https://github.com/reticlehq/reticle --skill replay-user-flows

Vor dem Start

  • Die Installation umfasst weder Modellabo noch API-Kontingent oder Dateizugriffsrechte.
  • Sterne und Installationen zeigen Aktivität, keine unabhängige Qualitäts- oder Sicherheitsprüfung.
Originales Skill-Dokument

Aus dem Quell-Repository gerendert; Überschriften, Beispiele, Code, Tabellen, Links und Bilder bleiben erhalten.

Record a journey once, re-verify it forever

Exploring an app to find a journey is the expensive part, and re-driving it with a model pays that cost again on every change. Reticle flows pay it once: the journey is saved with semantic anchors and replayed deterministically afterwards.

Needs Reticle wired in the project. Not there? RETICLE_INSTALL_SOURCE=npx_skill npx @reticlehq/server@latest init, then the `install-and-verify` skill.

Record

You do not have to ask. A drive is saved as a flow automatically when the session ends, written to .reticle/flows/. Commit it: any agent on the repo can then replay it.

What decides whether it is worth committing is how you drove it. A step keeps a consequence only when you declared one, so drive the golden path like this:

reticle_act_and_wait({ sessionId, ref, action: "click", until: { kind: "signal", name: "task:created" } })

That step replays as a test. A bare reticle_act saves a click with nothing to prove, and replays green through any regression.

To name a flow deliberately rather than take the automatic one, reticle_record and reticle_flow_save do it through reticle_run { tool, args }. Neither is advertised, and neither needs to be: reticle_run is on the default surface and dispatches to any registered tool by name. RETICLE_ADVERTISE_ALL_TOOLS=1 advertises them outright instead, which suits a suite that calls by name rather than a running agent.

Annotate the business outcome, not just the clicks, so a replay proves the journey achieved something. Extended surface, like the two above:

reticle_run({ tool: "reticle_annotate", sessionId, args: { flow: "create-task", kind: "intent", text: "create a task and see it in the list" } })
reticle_run({ tool: "reticle_annotate", sessionId, args: { flow: "create-task", kind: "success-state", signal: "task:created" } })

You do not need to add `data-testid` first. A step whose element has no testid is anchored on its component and source location automatically, and a testid-preserving refactor still replays green.

Replay

reticle_verify({ sessionId, action: "change", files: ["src/tasks/TaskList.tsx"] })

That replays the flows covering those files. To replay one named flow directly, reticle_flow_replay is reached through reticle_run.

Three statuses, and the failures are legible rather than blind:

statusmeansnext
okevery anchor resolved, every expectation helddone
driftan anchor missed: a renamed testid, a signal that never firedread decision.nextAction; it names the file:line and the closest surviving anchor
errorthe flow file is missing or invalid, or a step failed at runtimefix from the error envelope's failed step

On drift, reticle_verify { action: "heal" } proposes the nearest-match rebind so flows do not rot. Apply it when the rename was intentional; treat it as a finding when it was not.

Re-verify the whole suite after any change

reticle_verify({ sessionId, action: "flows" })
// → { status, total, passed, failed, failures: [{ flow, verdict, whatChanged, whereInSource, nextAction }] }

One call, every saved flow, no model per flow. Only failures carry detail, so a green suite is cheap to check. Build → flow_verify → fix from each nextAction → repeat is the regression loop, and it is the point of recording in the first place.

Only the flows your change could have broken

On a large suite, replaying everything after a one-file edit is waste. Hand it the diff instead:

reticle_verify({ sessionId, action: "change", since: "HEAD~1" })

It works out which saved flows cover the files you edited and replays only those. Give it a git ref or the file list. Use this in the inner loop and flow_verify before you ship: the narrow one is fast, the whole one is the guarantee.

Which of your flows actually prove anything

reticle_run({ tool: "reticle_domain", sessionId })   // not advertised, one hop away
// → { flowCount, coverage: { asserted, presenceOnly, assertionFree }, gaps: { declaredUntestedSignals, … } }

A recorded flow that asserts nothing replays green through any regression: it proves the clicks still resolve, not that the app still works. Check this after a recording session: anything landing in assertionFree needs an annotate pass with a success-state, or it is decoration.

When NOT to record

A journey you will run once is cheaper to drive with reticle_act_and_wait and forget. Record the flows that define the product (the ones a regression in would be a bad day) and leave exploratory drives unsaved. A suite of forty half-meant flows costs more attention than it returns.

Honesty

A replay reports what happened. drift is not a pass, and healing a flow to make it green when the app genuinely broke is the one thing that makes the whole suite worthless. If the rename was not intentional, the drift is the finding: report it with the whereInSource pointer.


Full flow reference, one page: curl https://docs.reticle.sh/flows.md. Index of everything: curl https://docs.reticle.sh/llms.txt.

Verwandte Aufgaben

aus demselben Repository

Weitere Skills

Alle Skills
reticlehq
Community

reticle

Install, instrument and verify this running web app from the inside (DOM, network, routing, console and framework state) instead of screenshots or guessing. Drives one real flow end to end and returns a verdict with the file:line to fix. Use when the user asks to set up or install Reticle, when a user-facing change needs proving before you call it done, when a test passes but the UI is broken, or when the user types /reticle.

Installationen / 1h
1
GitHub Stars
1285
Aktualisiert
30. Okt.
reticlehq
Community

audit-my-app

Sweep a whole running web app for what is broken, without writing a script or knowing the codebase. Clicks every reachable control and reports dead buttons, console errors, failed requests, and places where the API and the screen disagree. Use on an unfamiliar codebase, before a release, after a big merge or dependency bump, when the user asks for a smoke test or a health check, or when someone says "just check everything still works".

Installationen / 1h
1
GitHub Stars
900
Aktualisiert
26. Sept.
reticlehq
Community

debug-broken-ui

Find out why something in a running web app does not work, when the console is empty and the code looks correct. Reads the click, the request, the store and the console together and returns the file:line to open. Use when a button does nothing, a form will not submit, data will not load, a page renders blank or stale, a modal will not close, or the user says "it's broken" and the code review says it is fine.

Installationen / 1h
1
GitHub Stars
900
Aktualisiert
26. Sept.
reticlehq
Community

fix-what-i-pointed-at

Pick up the bugs a human flagged by pointing at them in the running app, each arriving with the element, the note they typed, and the source file and line. Use when the user says they marked or flagged something, when starting a session on an app someone has been clicking through, when a designer or PM has left feedback in the UI, or when the user describes a problem as "that button there" without saying which file.

Installationen / 1h
1
GitHub Stars
900
Aktualisiert
26. Sept.