# Run your first loop

Prerequisites: telemetry flowing ([instrument](/docs/instrument-ai-sdk)) and a
[connected agent](/docs/connect-your-coding-agent). Give the lake ~90 seconds
after your first events, then ask your agent:

> Observe and diagnose the last hour.

## What happens

1. **Observe** — the agent claims the window (`loopops_observe`). Claims never
   overlap: what was handled stays handled; next observe starts where this one
   ended.
2. **Diagnose** — `loopops_diagnose` returns the improvement packet. Its FIRST
   field is `memory`: what's already verified, what regressed, what has proof
   blocked, and what's in flight — the agent never re-diagnoses last week or
   mistakes a stopped verifier for active work. Then evidence-backed
   candidates, each with cited `evidence_ids`, a stable `cluster_id`, a
   server-computed status
   (`new | in_progress | verification_blocked | verified | regression`), token
   burn, and `replayable_count`.
3. **Decide** — `loopops_decide` first admits the cited diagnoses as
   canonical Issues. Its `recommended_next` is the agent's proposal, so every
   new Issue remains **Needs you**. After the checkpoint, your choice is recorded
   separately with `loopops_issue_decide`: patch, observe, defer, or skip,
   with your identity, timestamp, and rationale.
4. **Act + record progress** — the agent edits and tests through its normal
   repository workflow. Only an Issue with a patch disposition is selected; the
   fix attempt records `diagnosed` first to bind its evidence and
   identity. `loopops_improve` then records the stages reached
   (`diagnosed → approved → issue_opened → pr_opened → merged`); issue and PR
   milestones are optional. External writes still happen in **your** tools
   after **your** approval.
5. **Verify** — after the fix ships, `loopops_verify` compares the windows on
   both sides of the boundary. It **refuses a verdict on no data** — "merged"
   never silently becomes "fixed". Merged runs are also auto-verified
   server-side once their window elapses. Automatic retries are bounded: after
   eight `no_data` attempts, the server records `verification_blocked` with
   its reason and retry count. The agent then inspects the evidence window,
   waits for comparable traffic, or revises the proof plan instead of claiming
   verification is still moving. A joined exact comparison that completes but
   does not improve records `verification_failed` immediately and reopens the
   Issue as a regression; it is not mislabeled as an evidence blocker.

## Prove a prompt fix before shipping

If a cluster has `replayable_count > 0`, `loopops_replay` re-runs the captured
failures against your candidate prompt/model change and grades them — evidence
for the approval ask, before anything ships.

## If it holds — and if it doesn't

A verified fix shows up in the console's Loop tab with its before/after rates.
If the same cluster re-fires on a **later** `service.version`, it flags as a
regression on the next observe — regressions can't hide.

**Next:** [Hand an issue to an agent →](/docs/issue-handoff)