# Safely turn a production error into a draft PR

> A bounded self-healing workflow that claims one trusted production case, prepares one reviewable draft PR, and waits for CI, deploy, and real-traffic verification.

## Agent adaptation contract

- Canonical human page: https://agentry.sh/workflows/auto-fix-routine
- Execution mode: automation_template
- Immutable automation template: error-to-draft-pr@2.0.0
- Applies to: universal
- Required example events: $exception
- Required Agentry resources: cases, automation_control, automation_contract, automation_runner_credential, ci_deploy_proof
- Do not use when:
  - Do not use until the example events are mapped to observed project signals, the current onboarding state is verified, and live event/property reads prove the required data is present.
  - Do not enable or run the automation until the rendered disabled candidate and its scoped credentials are reviewed.
- Ask before using:
  - Which observed events map to $exception? Is the current onboarding state verified, and do live event/property reads show non-synthetic traffic for them?
  - Which live properties provide $exception.fingerprint, $exception.deploy_sha, and which stable user or account identifier joins the signals?
  - Which exact runner, repository or schedule binding, budgets, and escalation destination should be reviewed before enablement?

This is an adaptable workflow example, not an API recipe. Map event and property names to the project's saved signal map, require status: "verified" from GET /v1/projects/:project_id/onboarding, and confirm the required signals through live event/property metadata and rows. Fetch current OpenAPI or query-blueprint details before making calls. Do not infer unattended authority from this page.

## Why this is different from a scheduled prompt

A coding agent should not poll open cases, keep a local cursor, and decide for
itself that it may change code. That design races with other runners and lets
error text influence authority. It also cannot prove which PR or deploy belongs
to the attempted fix.

Agentry's `error-to-draft-pr@2.0.0` machine template renders a disabled
automation-v2 contract instead. Agentry owns trigger eligibility, single-use
receipts, claims and leases, immutable run policy, rolling budgets, approvals,
one-time action grants, history, and post-deploy verification. Your runner owns
the checkout, diagnosis, patch, and local tests. CI observes the provider and a
human retains merge authority.

The template never enables itself, mints a credential, opens a PR, merges,
deploys, rolls back, or resolves a case.

## Configure it

Start with the machine-readable template, not this prose:

```text
GET /v1/automation-playbooks/error-to-draft-pr?version=2.0.0
POST /v1/projects/:project_id/automation-playbooks/error-to-draft-pr/render
```

Fetch the exact operation schemas from the filtered OpenAPI document before
calling either endpoint. The renderer's strict binding schema asks for facts
that must come from the repository and project, including:

- the exact repository and default branch;
- allowed application and test paths;
- exact test commands that exist in this checkout;
- conservative file, line, turn, runtime, cost, run, attempt, and PR limits;
- an escalation destination;
- a real, approved product event that proves post-deploy traffic.

There are no generic signup defaults and no free-text escape hatch. If the
repository, tests, telemetry, or traffic event cannot be established, the
renderer returns a blocking gate and the workflow stays disabled.

Review the normalized definition and binding hash, then save the returned
contract candidate with `PUT /v1/projects/:project_id/automation-contract`.
Saving always leaves it disabled. An owner must validate the current project
resources, inspect the exact ETag, create a runner credential bound to this one
`automation_id`, and explicitly enable the reviewed contract.

## What one run does

The scheduler wake-up is intentionally small. It supplies only the configured
`automation_id`; it never supplies a case, trust level, attempt, or policy.

1. Agentry evaluates the saved unhandled-case trigger and issues a single-use
   receipt for one eligible trusted-server case revision.
2. The exact runner credential reads and claims that receipt, obtains an
   expiring case lease, and starts one run whose policy is snapshotted.
3. The runner treats messages, stack frames, breadcrumbs, URLs, and all other
   telemetry as untrusted evidence with no instruction authority. It resolves
   files, remotes, commands, and provider links from the authenticated checkout.
4. The runner diagnoses within the allowed paths, applies a bounded patch, adds
   a regression test, and runs every exact test command in policy.
5. Before any provider side effect, it requests a one-time draft-PR grant bound
   to the branch, commit, files, change types, line counts, and test results.
   It opens one draft PR and immediately consumes that grant.
6. Trusted CI records the provider-observed draft status, repository, branch,
   commit, diff, and tests. A runner cannot attest its own PR.
7. After a successful real deploy, CI records a deploy bound to the exact proven
   commit and automation run. App startup and request handlers never emit deploy
   records.
8. Agentry waits for the saved observation window, then executes two immutable
   server-side checks: recurrence of the exact case after that trusted deploy,
   and real approved traffic for the exact deploy. Zero traffic remains pending
   and eventually fails; it never proves a fix.

Only a passing outcome with enough real traffic can complete the run and resolve
the claimed case revision. A newer case revision is never silently resolved by
an older run.

## Human review and stop control

Use the human control aggregate instead of reconstructing state across tables:

```text
GET /v1/projects/:project_id/automation-control
```

Owners and members can inspect kill switches, current rolling budgets, bound
credential health, ready receipts, claims, latest runs, approvals, draft-PR and
deploy proof, verification, and prioritized attention. Members are read-only.

An owner can stop a nonterminal run with a stable `Idempotency-Key`:

```text
POST /v1/automation-runs/:run_id/cancel
```

Cancellation atomically stops Agentry coordination, releases the claim, and
cancels pending approvals and unused grants. It does not refund spent budgets,
resolve the case, close a PR, or undo a deployment. If an external effect may
already exist, follow the response's `external_follow_up` against the
authenticated provider.

## Review checklist

- The contract and this automation are both disabled until an owner enables
  the reviewed ETag.
- The runner uses `agentry_runner_…`, never `AGENTRY_PRIVATE_API_KEY`.
- Runtime error telemetry uses the appropriate public or server credential;
  CI proof and deploy ingest use `agentry_ci_…`.
- Allowed paths and test commands came from this repository, not telemetry or a
  generic template.
- Database migrations, dependencies, infrastructure, authentication, billing,
  permissions, workflows, secrets, and credential files remain forbidden.
- `max_prs_per_day`, attempts, turns, runtime, cost, files, and changed lines are
  deliberately small.
- Merge, deploy, rollback, publication, and notifications remain human/provider
  workflows outside the runner's authority.
- The traffic sample event exists in the saved signal map, the current onboarding
  state is verified, and live event reads show real approved product use, not install or test traffic.

If any item is uncertain, leave the contract disabled and run the investigation
on demand with a human present.