cy0307/awesome-loop-engineering

1# Loop Pattern Library2 3Twenty operational patterns turn the Loop Contract into repeatable ways of working. Choose a pattern because recurring jobs fail in different ways: a PR can wait on checks, a rollout can breach a threshold, and a security review can cross an approval boundary. Each needs its own trigger, permissions, evidence gate, state, budget, and human handoff even when the underlying agent is the same.4 5Use a loop when the work returns, an external signal can verify progress, useful state should survive between runs, and action can be bounded. Prefer one supervised agent run when the task is one-off, completion is mainly subjective, or a safe permission boundary cannot be stated.6 7## Use The Library In Three Steps8 91. Start from the recurring symptom and verified outcome in the coverage map below.101. Open the pattern to review its trigger, external gate, state, failure boundaries, and worked example.111. Adapt its linked JSON contract to your permissions and budgets, then choose a [runtime starter](../examples/runnable/README.md).12 13The layers have different jobs:14 15| Layer | Question it answers | Artifact |16| --- | --- | --- |17| **Pattern** | How should this class of recurring work operate? | Human-readable operating playbook |18| **Contract** | What exactly may this loop read, change, verify, spend, and escalate? | Schema-valid JSON in [`examples/`](../examples/README.md) |19| **Runtime starter** | Where and how does the contract execute? | Copy/paste and executable starters in [`examples/runnable/`](../examples/runnable/README.md) |20 21## Coverage Map22 23### Build And Maintain24 25| Symptom | Pattern | Verified outcome |26| --- | --- | --- |27| A pull request is stalled | [PR babysitter](pr-babysitter.md) | Required checks pass, review threads are resolved, and merge state is current |28| CI keeps failing | [CI repair loop](ci-repair-loop.md) | The original failing command passes with a scoped patch |29| Documentation may be stale | [Docs drift collector](docs-drift-collector.md) | Verified code/docs mismatches are patched and examples still run |30| Dependency updates pile up | [Dependency triage loop](dependency-triage-loop.md) | Safe updates pass tests and risky upgrades have an owner-backed escalation |31| Bugs need systematic discovery | [Bug hunting loop](bug-hunting-loop.md) | Each accepted finding has reproducible steps or a failing test |32| Release notes are incomplete | [Release-note loop](release-note-loop.md) | Every shipped change maps to a merged source and audience-facing note |33 34### Operate And Observe35 36| Symptom | Pattern | Verified outcome |37| --- | --- | --- |38| A rollout needs watching | [Deploy verifier](deploy-verifier.md) | Synthetic checks and rollout thresholds remain within policy |39| An incident just paged | [Incident response loop](incident-response-loop.md) | Impact, evidence, timeline, and accountable owner are recorded |40| A dataset keeps drifting | [Data-quality loop](data-quality-loop.md) | Hard quality rules pass before a new version is promoted |41| Agent spend is rising | [Cost-control loop](cost-control-loop.md) | Spend falls on a comparable workload without quality regression |42| Model choice is ad hoc | [Model-routing loop](model-routing-loop.md) | Routing decisions meet quality, latency, privacy, and cost tolerances |43| Latency, throughput, or memory regressed | [Performance regression loop](performance-regression-loop.md) | A controlled benchmark confirms recovery with correctness intact |44 45### Learn And Optimize46 47| Symptom | Pattern | Verified outcome |48| --- | --- | --- |49| Feedback is noisy and unsorted | [Feedback clusterer](feedback-clusterer.md) | Themes cite source items and separate frequency from severity |50| Agent evaluations regressed | [Evaluation regression loop](evaluation-regression-loop.md) | Targeted evals return to the accepted baseline without scorer changes |51| A system should improve against a metric | [Benchmark optimization loop](benchmark-optimization-loop.md) | Repeated measurements confirm an improvement with protected metrics intact |52| An agent's knowledge is stale | [Knowledge freshness loop](knowledge-freshness-loop.md) | A versioned corpus passes provenance, freshness, retrieval, and leakage gates |53| Recurring runs repeat old mistakes | [Agent memory lifecycle loop](agent-memory-lifecycle-loop.md) | Governed records pass provenance, scope, contradiction, and recall gates |54| Parallel agents collide on one repo | [Fleet coordination loop](fleet-coordination-loop.md) | Isolated workers land serially through a verified merge queue |55 56### Govern And Protect57 58| Symptom | Pattern | Verified outcome |59| --- | --- | --- |60| A sensitive change needs review | [Security review loop](security-review-loop.md) | Findings cite concrete evidence and approval boundaries stay intact |61| A change needs formal sign-off | [Enterprise approval loop](enterprise-approval-loop.md) | Every required gate has a recorded decision and audit trail |62| A UI introduced an accessibility failure | [Accessibility regression loop](accessibility-regression-loop.md) | The exact regression is fixed and required human criteria are approved |63| An agent system needs adversarial testing | [Adversarial red-team loop](adversarial-red-team-loop.md) | Confirmed findings are reproduced, minimized, privately reported, and regression-tested |64 65## Choosing Between Similar Patterns66 67| If the work sounds like... | Choose | Not |68| --- | --- | --- |69| "A known code change may be unsafe" | Security review | Adversarial red team, which actively discovers behavior failures |70| "Find new failures in a sandboxed agent" | Adversarial red team | Bug hunting, which is broader and not threat-model driven |71| "Our eval score dropped" | Evaluation regression | Benchmark optimization, which seeks new improvement from a stable baseline |72| "Make this system measurably better" | Benchmark optimization | Performance regression, unless the target is specifically latency, throughput, memory, or cost |73| "Our repo docs no longer match code" | Docs drift | Knowledge freshness, which maintains a multi-source retrieval corpus |74| "The retrieval corpus is stale" | Knowledge freshness | Data quality, unless the artifact is a general dataset rather than an agent knowledge index |75| "A scanner found an accessibility issue" | Accessibility regression | General CI repair, because automated checks do not cover all human accessibility criteria |76 77Compare trigger, state, gate, budget, escalation, and runtime across every pattern in the [full matrix](MATRIX.md).78 79## Pattern Quality Bar80 81A pattern qualifies for this library only when it:82 83- solves a recurring job that is materially distinct from an existing pattern;84- has an external feedback signal stronger than the acting model's opinion;85- names durable state, a hard budget, and a human handoff;86- states what the loop must not do;87- includes a worked scenario and a schema-valid contract;88- can map to at least one practical runtime without assuming unlimited permissions.89 90Reject patterns whose only gate is "the agent says it looks good." Prefer exit codes, score distributions, changed files, source manifests, trace IDs, dashboard thresholds, screenshots, or named reviewer decisions.91