| license | BSL-1.1 |
| name | dag-mutation-strategist |
| description | Decides HOW to mutate a DAG when a node fails, quality is below threshold, or new information changes the plan. Selects from mutation strategies (add node, replace agent, fork paths, loop back, downgrade model) based on failure type, cost budget, and execution history. Activate on "DAG failed how to fix", "mutation strategy", "replan on failure", "adaptive DAG", "recovery strategy", "what to do when node fails". NOT for detecting failures (use dag-quality), executing mutations (use dag-planner), or runtime execution (use dag-runtime). |
| allowed-tools | Read,Grep |
| metadata | {"category":"DAG Framework","tags":["dag","mutation","strategist","dag-failed-how-to-fix","mutation-strategy"]} |
| category | Agent & Orchestration |
| tags | ["dag","mutation","strategy","dynamic","adaptation"] |
DAG Mutation Strategist
Decides HOW to mutate a DAG when things go wrong. Given a failure diagnosis from dag-quality or dag-ops, selects the optimal recovery strategy.
When to Use
✅ Use for:
- Choosing a mutation strategy after a node fails
- Deciding between retry, replan, fork, or escalate
- Adapting to mid-execution discoveries that change the plan
- Cost-aware recovery (don't spend $0.50 recovering a $0.01 failure)
❌ NOT for:
- Detecting failures (use
dag-quality)
- Executing the mutation (use
dag-planner to rewire, dag-runtime to execute)
- General error handling in code
Strategy Selection
flowchart TD
F[Failure detected] --> T{Failure type?}
T -->|Transient: API timeout, rate limit| R[Retry with backoff]
T -->|Model: wrong format, refusal| M{Budget allows upgrade?}
M -->|Yes| U[Replace with stronger model]
M -->|No| P[Rephrase prompt, same model]
T -->|Contract: output schema mismatch| C[Retry with explicit schema in prompt]
T -->|Quality: below threshold| Q{Iteration count?}
Q -->|< max| L[Loop back with feedback from dag-quality]
Q -->|≥ max| E{Challenger skill available?}
E -->|Yes| SW[Swap to challenger skill]
E -->|No| HG[Escalate to human gate]
T -->|Logic: wrong approach entirely| D{Cost of replan vs remaining budget?}
D -->|Replan < 30% of budget| RP[Replan affected subgraph]
D -->|Replan > 30%| HG
T -->|Cascade: upstream caused this| FIX[Fix root cause node first]
FIX --> R
Strategy Catalog
| Strategy | When | Cost | Risk |
|---|
| Retry with backoff | Transient failures (timeout, rate limit) | Same as original (~$0.001-0.01) | Low — usually works in 1-3 retries |
| Rephrase prompt | Model refused or misunderstood | Same as original | Medium — may not fix the root cause |
| Upgrade model | Cheap model failed on complex task | +$0.01-0.10 | Low — stronger model usually succeeds |
| Downgrade + simplify | Expensive model failed, budget tight |
