Skip to content

dvy1987/agent-loom / .agents/skills/dynamic-routing

dynamic-routing

Verified

Select alternative execution paths when a plan step fails — branch on outcomes instead of blind retry. Load when a structured plan step fails, an unexpected observation arrives, or the user asks what to try next after an error. Also triggers on "try another approach", "route around this failure", "replan on failure", "if X fails try Y", or outcome-based branching during multi-step work. Pairs with structured-planning and debug-and-fix. Does not replace root-cause debugging — adds plan-level path selection.

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:

RouteWhen
Alternate toolSame goal, different tool/path
DecomposeStep too large — split into Sx.1, Sx.2
Rollback + revisePrior step assumption wrong — mark prior revised, insert fix step
Escalate model tierExecuting model tripped a model-selection tripwire (same test failed 2x, 3 attempts at one fix, unscoped design question) — announce the tier switch; the HUMAN changes models (advisory, per model-selection)
AbortGoal infeasible with current constraints — mark aborted, stop
Debug handoffRoot cause unclear — debug-and-fix, resume plan after fix

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

ExcuseReality
"Retry might work"Same inputs → same failure. Change the path.
"Replan from scratch is faster"Loses done-step evidence and trace links.
"Error is obvious"Write the hypothesis anyway — audit trail.
"Skip delta log"Next agent won't know why the plan changed.
"Debug later"If layer=code, debug now before continuing plan.

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]
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 319kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 319kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 319kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 196kUpdated Claude CodeCodexVerifiedInstall