Loop Engineering

Design a loop as a control system, not a repeated prompt. Its only valid form is:

goal + state + tools + budget
            |
            v
plan -> act -> observe -> independently verify -> decide
  ^                                               |
  |---------------- continue / stop / escalate ---|

Use scripts/validate_loop_contract.py before starting a loop. Do not bypass a failed contract.

Usage Template

Use loop-engineering for this task.

Objective: [measurable outcome]
Scope: [owned files, systems, or outputs]
Evidence: [test, metric, fixture, review, or inspection]
Limits: [iterations, time, tool/token/request budget]
Permission boundary: [allowed writes and approval gates]

Success Metrics

• A valid contract names the metric, independent verifier, finite caps, recovery path, and durable write-back.
• The selected topology is the lowest-complexity topology that can produce independent evidence.
• The final receipt distinguishes verified success, budget stop, stall, and blocked state.

1. Admit Or Reject The Loop

Use a loop only when the work is repeatable, the output can be checked, and each iteration can leave inspectable evidence.

Reject a loop when its only stopping rule is “until satisfied,” “keep improving,” or “run forever.” Convert those requests into a metric, an acceptance fixture, a review queue, or a one-shot draft.

2. Create The Loop Contract

Create .agent-state/loop-contract.md or an equivalent durable state file before the first action. Use this exact shape:

# Loop Contract

- Objective: Reduce the selected test suite's failures to zero.
- Scope: `packages/payments/**` and its tests only.
- Non-goals: No API redesign, dependency upgrades, or production deployment.
- Owner: Primary agent; checker owns verification only.
- Inputs: Failing test output and repository guidance files.
- State path: `.agent-state/payments-loop.md`.
- Success metric: Selected test command exits 0 with no skipped failures.
- Evidence: `pnpm test --filter payments` output and changed-file diff.
- Verifier: Independent test command plus a checker agent or reviewer.
- Topology: maker-checker.
- Max iterations: 5.
- Time limit: 45 minutes.
- Budget: 20 tool calls; stop before context or cost cap.
- Stop condition: Success metric passes, or any cap/stall condition fires.
- Write-back: Update `.agent-state/payments-loop.md` and the task log.
- Permission boundary: Local branch writes only; no push, merge, or production action.
- Recovery: Revert the last iteration if tests regress; escalate with evidence after two repeated failures.

Run:

python scripts/validate_loop_contract.py .agent-state/loop-contract.md --strict

Treat a budget cap or stall condition as a controlled stop, not success.

3. Run The Thin Loop

For each iteration:

1. Read only the contract, current state, last evidence, and minimum task context.
2. Plan one smallest reversible action that can affect the metric.
3. Act inside the contract's file, tool, and permission boundary.
4. Observe tool output, diffs, logs, tests, screenshots, or telemetry.
5. Have the declared verifier evaluate the evidence. The builder cannot be the sole verifier.
6. Record metric delta, changed files, evidence path, budget used, and next decision in state.
7. Stop, continue, or escalate according to the contract.

Keep context lean. Persist state and evidence in files rather than replaying a long chat transcript.

4. Select Topology Conservatively

Do not use manager-workers merely to make a task feel more autonomous. Escalate to agent-teams-command when real multi-agent ownership, IPC, or integration work is required. Escalate to harness-engineering when permissions, credentials, scheduling, or production observability are the primary problem.

5. Stop, Recover, Or Escalate

Stop successfully only when the declared verifier accepts the declared evidence. Stop without success when a hard cap fires.

6. Close The Memory Loop

At termination, write one compact receipt:

Result: success | budget-stop | stalled | blocked
Metric: before -> after
Evidence: command, output path, screenshot, or diff
Iterations: N / cap
Changes: files or external actions
Residual risk: what remains unverified
Next action: only if not successful

Promote reusable constraints to a project AGENTS.md, SOP, or related skill. Do not promote an unverified heuristic as a rule.

Quality Gates

• [ ] Contract passes validate_loop_contract.py --strict before execution.
• [ ] Success metric and stop condition are separately stated.
• [ ] Verifier is independent from the builder or backed by external evidence.
• [ ] Iteration, time, and tool/token/request budgets are finite.
• [ ] State, evidence, and write-back paths are durable and explicit.
• [ ] Production or external mutations have approval, rollback, and audit boundaries.
• [ ] Multi-agent use has independent ownership and an integration gate.
• [ ] Completion claim cites fresh verifier evidence; budget stop never masquerades as success.

Anti-Patterns

• Letting the builder score itself and treating that score as proof.
• Adding more agents before the task, metric, or ownership is clear.
• Treating “no errors observed” as success without a declared check.
• Carrying state only in chat memory.
• Running a scheduled or production loop without caps, rollback, and anomaly escalation.
• Repeating the same failed hypothesis without changing evidence or diagnosis.