failure-routing

name	failure-routing
description	Failure routing protocol. Use when routing test or review failures to the correct agent.

Failure Routing

Route failures by evidence.

Read the active heavy-task .agents/PROGRESS.md when one exists, plus the failing test/review output, before assigning ownership. For a review finding, read its artifact and route only <artifact-path>#F<n>. If a failure requires a durable handoff, write or request .agents/HANDOFF.md, then record that reference and route metadata in .agents/PROGRESS.md section 6. Issues / Routing only when the heavy-task ledger is active; otherwise retain it in todowrite until a durable handoff is needed.

• Backend: API errors, service logic, validation, persistence, migrations.
• Frontend: rendering, state, forms, client mapping, styles, browser behavior.
• Contract: backend response and frontend expectation disagree.
• Test fixture: setup, mocks, snapshots, seeded data.
• Environment: missing services, credentials, flaky infrastructure.
• Existing unrelated: failure predates or is outside the assigned change.
• Ambiguous: ask planner or user; do not guess.

Route with exact artifact/finding reference or test evidence, owner, files or area, exclusions, and expected result. Do not rewrite review finding prose outside its artifact.

Preserve the source finding's [P0]–[P3] priority in every route and handoff. If creating a new actionable issue, assign one: [P0] is a universal release, operations, or major-usage blocker; [P1] is urgent next cycle; [P2] is a normal eventual fix; [P3] is low/nice-to-have. Do not translate priorities to Blocker, Important, or Optional.

Use the question tool when routing depends on user intent or risk acceptance.

Retry-loop limit

Prevent infinite fix loops by tracking attempts per issue key.

• Issue key: use the stable ISSUE-<n> from the active .agents/PROGRESS.md section 6. Issues / Routing, or create one in todowrite before routing routine work.
• Failed fix attempt: an owning agent made a fix for the same unresolved issue and a test run, review, or user report still shows that issue failing.
• Attempt ledger: record or update the issue key, priority, routed owner, explicit failed-attempt count, and last failure in the active .agents/PROGRESS.md section 6. Issues / Routing; for routine work, keep the same fields in todowrite and a boundary handoff when one is created.
• After 3 failed fix attempts on the same issue, stop before attempt 4.
• Escalate to the user with the issue key, owner, number of tries, and last failure.
• Log a blocker in the active .agents/PROGRESS.md section 7. Blockers, or in a routine-work boundary handoff, with the issue key, attempt count, last failure, and required user decision or plan revision.
• Reset the attempt count only when the issue passes validation or is intentionally re-scoped with a new issue key.

Routing record for .agents/PROGRESS.md

For an active heavy-task ledger, add or update one row in ## 6. Issues / Routing with; otherwise retain the same fields in todowrite and a boundary handoff when needed:

• ID: ISSUE-<n>.
• Priority: the source [P0]–[P3] label, preserved exactly.
• Source: <artifact-path>#F<n>, test run, or user report.
• Description: only non-review test/user evidence; review routes retain the reference.
• Classification: Backend, Frontend, Contract, Test fixture, Environment, Existing unrelated, or Ambiguous.
• Routed To: agent or user owner.
• Failed attempts: explicit integer from 0 through 3; stop before 4.
• Status: open, routed, in-progress, resolved, deferred, wont-fix, or blocked.
• Resolution: next action or final resolution.

Failure handoff expectations

When writing .agents/HANDOFF.md, include the issue ID, failure source, classification, minimal exact evidence, implicated files/areas, why the owner was chosen, required result, out-of-scope boundaries, suggested validation, and required .agents/PROGRESS.md updates.