Dynamic Routing

When a step fails or observation ≠ expected, you reflect, branch, and revise the plan — never blind-retry the same action. Output is an updated plan delta + chosen alternate path.

Hard Rules

Ground reflection in step evidence — cite tool output, error message, or test failure. Blind retry of the identical action is forbidden unless the reflection identifies a transient cause (network, rate limit) with a documented backoff. Every route decision appends to the plan's Plan delta log in .agent-loom/plans/<task-id>.md. Prefer path recombination (insert/replace remaining steps) over full replan when <50% of steps remain. If failure is a bug in existing code, route to debug-and-fix before resuming the plan.

Workflow

Step 1 — Capture failure context

From the failed step: step_id, expected vs actual, error text, layer (tool/env/code/plan).

Step 2 — Structured reflection (3 lines max)

Hypothesis: [cause grounded in evidence]
Layer: [plan | tooling | code | environment]
Actionability: [plan revision | debug-and-fix | escalate user]

Step 3 — Select route

Read references/ROUTE-PATTERNS.md. Pick one:

Step 4 — Update plan

1. Mark failed step failed or revised.
2. Insert/replace pending steps.
3. Append delta log row.
4. Run structured-planning lint via plan_lint.py.

Step 5 — Resume

Return control to structured-planning at the new first pending step.

Gotchas

• Retrying without changing inputs is not routing — it's a loop.
• Full replan discards useful done steps — patch the remainder.
• Environment flakes need explicit transient tag + max 1 retry with backoff.
• Tier escalation is advisory: announce switch to [tier/model] and WAIT — never assume the harness can switch models itself. Tier escalation (who executes) and path revision (what to do) are separate decisions; they can combine.

Output Format

## Dynamic route — [task_id] / [step_id]

Reflection:
- Hypothesis: [...]
- Layer: [...]

Route chosen: [alternate tool | decompose | rollback+revise | abort | debug handoff]

Plan delta:
| at | step_id | from | to | reason |
|----|---------|------|-----|--------|
| [...] |

Resume at: **Sx** | Handoff: debug-and-fix | Aborted

Examples

Teaser: S2 migration fails (table exists) → route decompose → S2.1 check schema, S2.2 apply delta only.

Full pairs: references/examples.md

Common Rationalizations

Verification

• Reflection cites step evidence
• Plan delta log updated
• No identical blind retry
• plan_lint.py passes after revision

Red Flags

• Same action repeated after failure
• Plan revised without delta log entry
• Code bug worked around in plan without debug-and-fix

Prune Log

Last pruned: 2026-07-08

• Added Escalate-model-tier route wired to model-selection tripwires (agent-loom upgrade Phase 2)

Impact Report

Route: [task_id]/[step_id] | Decision: [route type] | Resume: [step or handoff]