nguyenthienthanh AI-consumed reference. Optimized for Claude to read during execution. Human-readable explanation: see docs/architecture/HIERARCHICAL_PLANNING.md or docs/getting-started/ depending on topic.
Failure Classifier
STATUS — v3.7.0-alpha.2 (Milestone B).
Classifies T4 task failures so master-planner can decide: retry, self-heal, replan, or escalate.
Failure classes
| Class | Name | Trigger | Recommended action |
|---|---|---|---|
| F1 | transient | Network timeout, file lock, ECONNRESET, rate limit, flaky CI | Retry with backoff (max 3) |
| F2 | local-logic | Test fails, type error, lint error, assertion mismatch | Self-heal-propose (Milestone E) or single retry |
| F3 | local-design | Story acceptance unreachable as designed; signals: same test fails after 2 fixes, or output drift > 50% from plan | Replan story (re-decompose T3) |
| F4 | story-level | Sibling tasks broken, dependency contract violated, deviation_score ≥ 0.7 | Replan feature (re-decompose T2) |
| F5 | architectural | Cross-feature impact, mission-level constraint violated | Freeze + escalate to user |
F6 — conflict-induced (added in v3.7.0-beta.2): when cause: conflict is set on the failure signal OR conflict_id is non-null, classifier returns class F6 with confidence 0.95 and routes to conflict-arbiter agent (NOT replanner). The arbiter applies the decision table from rules/workflow/conflict-arbitration-policy.md.
Classifier inputs
- Failure event from post-execute-update-node hook:
{tool, exit_code, stderr_tail, files_touched} - Active task node (status, failed_attempts, replan_budget_remaining)
- Last 10 history.jsonl events for the task
- Failed test output (when available)
Decision rules (deterministic, evaluated top-down — first match wins)
1. exit_code == 0 → not a failure; abort classification
2. failure.cause == "conflict" OR failure.conflict_id is non-null → F6
3. stderr matches /ECONNRESET|ETIMEDOUT|EAI_AGAIN|429|503|rate limit/i → F1
4. failed_attempts >= 3 AND same stderr_hash as last 2 attempts → F3
5. files_touched intersects sibling task's files_touched (from history) → F4
6. failed_attempts == 1 AND stderr matches /TypeError|SyntaxError|test failed|assertion/ → F2
7. deviation_score(node) >= 0.7 → F4
8. ancestor_T1.intent contradicted by failure evidence → F5
9. default → F2
Output schema
{
"class": "F3",
"confidence": 0.78,
"evidence": [
"failed_attempts=3",
"stderr_hash matches last 2 attempts",
"test_ref tests/auth/jwt.test.ts has been edited 4 times in revision history"
],
"recommended_action": "replan_story",
"node_id": "TASK-00101",
"parent_node_id": "STORY-0042"
}
Confidence scoring
F1 transient: 0.95 (regex match is reliable)
F2 local-logic: 0.85 (single attempt heuristic)
F3 local-design: 0.75 (multi-attempt + same hash)
F4 story-level: 0.80 (file overlap is signal-rich)
F5 architectural: 0.65 (semantic match — lowest confidence)
If confidence < 0.6 → emit class: F2 with the action single_retry_then_escalate and surface to user.
What this skill does NOT do
- Does NOT call an LLM (deterministic only — see Q1 decision)
- Does NOT decide retry/replan itself (that's master-planner)
- Does NOT mutate the plan tree
- Does NOT itself dispatch arbitration on F6 — emits the class with
recommended_action: arbitrateandroutes_to: conflict-arbiter; master-planner picks up the dispatch
Tie-Ins
- Spec: §9.3
- Decisions: Q1 (deterministic), Q5 (deviation_score formula in
replan-thresholds.md) - Agent: master-planner — consumes classifier output for decision engine
- Agent: replanner — invoked when class is F2/F3/F4
- Rule:
rules/workflow/replan-thresholds.md— deviation_score formula - Hook:
hooks/post-execute-update-node.cjs— invokes this skill on failure