Loop Engineering

Loop Engineering

<skill_contract> <input>A repeatable task with inspectable state, finite budgets, permissions, and an independent verifier.</input> <output>A validated Trigger -> Execute -> Verify -> State contract plus resumable run receipts.</output> <done>The declared metric or stop condition is supported by fresh validator and verifier evidence.</done> <non_goals>Dependency-graph orchestration, unbounded autonomy, or self-certified completion.</non_goals>

Build loops only when repeated execution creates evidence. Every loop needs admission, a validated contract, durable state, independent evaluation, bounded retries, stop/recovery rules, and a final receipt.

Usage Template

Provide: objective, trigger, scope/non-goals, inputs, state/artifact paths, metric, verifier, permissions, budgets, stop condition, recovery, and write-back. See references/ci-repair-loop-example.md for a worked contract.

Workflow

<intake>

Select one mode:

• Goal: run until a defined end state or cap.
• Loop: poll/iterate while eligible work exists.
• Automation: start from an external schedule/event; the trigger is not execution evidence.
• AutoResearch: vary experiments against an objective metric in a sandbox.

Admit only if work is repeatable, outputs are inspectable, a verifier exists, failures are recoverable, and autonomy is worth the orchestration/review cost. Otherwise use a one-shot workflow.

Use graph-engineering instead when explicit data dependencies, independent branches, typed joins, or node-local recovery create measurable value. A Graph node may use this Loop contract for local repetition; Graph width does not replace finite Loop depth.

</intake>

<unknowns_gate>

Classify unknowns as known, probeable, testable, or blocked. Missing objective, verifier, permission boundary, budget, or recovery is NEEDS_INPUT; do not infer these controls from intent. Unknown implementation details may be resolved inside the loop only when the probe is bounded and reversible.

</unknowns_gate>

<execute>

Write this contract before acting:

Objective:                 Mode: Goal | Loop | Automation | AutoResearch
Trigger:                   Scope:                 Non-goals:
Owner:                     Inputs:
Artifacts path:            State path:            Work clock:
Success metric:            Evidence:              Verifier:
Topology: single-agent | maker-checker | manager-workers
Max iterations:            Time limit:            Budget:
Review budget:             Stop condition:
Write-back:                Permission boundary:   Recovery:

Validate it with scripts/validate_loop_contract.py --strict. Then iterate:

1. Observe: load durable state, fresh environment evidence, budgets, and last error.
2. Orient: update one hypothesis; choose the smallest action that can change the metric.
3. Decide: check scope, permissions, expected evidence, and rollback.
4. Act: execute one bounded action and capture artifact/diff/receipt.
5. Verify: use a deterministic check or independent checker; compare metric and guardrails.
6. State: append diagnosis, action, evidence, delta, budget, and next decision atomically.
7. Stop/continue: stop on success, cap, permission boundary, regression, repeated signature, or no useful work.

Normalize the model/runtime termination signal after every action. complete still requires the declared verifier; tool_request returns proposed arguments to the host permission gate; checkpoint/truncation persists state before any continuation; refusal, error, or unknown escalates. Never infer completion from fluent prose or from the word "stop" alone.

For maintenance and queue loops, declare an allowed NO_OP outcome and its eligibility query. A quiet iteration is successful only when the query proves there was no eligible work, output count is within policy, and no side effect occurred.

Use single-agent by default, maker-checker for ambiguous/high-risk evaluation, and manager-workers only for genuinely independent work with an explicit integration gate.

If a validated Graph owns the dependency topology, this skill owns only the bounded retry behavior inside its declared loop nodes.

</execute>

<evaluate>

The verifier must test the declared result rather than reward activity. Check evidence freshness, metric movement, guardrails, scope, and state replay. For external or consequential actions, require approval and verified rollback before crossing the boundary.

</evaluate>

<retry_policy>

max_attempts equals the contract's finite max iterations. Retry only after a named diagnosis and a changed input, tool, scope, or strategy. Stop on the same failure signature twice, metric regression, exhausted review budget, or NO_PROGRESS.

</retry_policy>

<state_contract>

Persist {run_id, status, attempt, budget, evidence, unknowns, last_error, next_action} plus contract version, trigger receipt, hypothesis, action, normalized termination reason, artifact/diff, metric/guardrail delta, permissions, output count, no-op receipt, work clock, and recovery point. Append iterations; write current state atomically.

</state_contract>