dag-mutation-strategist

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