17. Error & Recovery Protocol
Scan: Three-tier response — data integrity threat (STOP + escalate), state inconsistency (fix + log), process issue (workaround + backlog).
Decisions: D24
17.1 Tiered Response
| Severity | Trigger | Response | Recovery |
|---|---|---|---|
| Tier 1 — Data integrity threat | Corrupt file, data loss, conflicting writes destroying content | Stop all writes immediately. Document the issue. Do NOT attempt automated repair. Escalate to human with #needs-human tag. | Human-guided only |
| Tier 2 — State inconsistency | Stale STATE.md, broken cross-references, missing frontmatter | Attempt recovery: re-read files, reconcile state, add missing fields. Log the issue and recovery action in session file. Continue work. | Agent-recoverable with documentation |
| Tier 3 — Process issue | Template not found, naming violation, ambiguous pipeline stage | Note the issue in session file. Work around it. Create a backlog idea for improvement. | Work around, improve later |
flowchart LR
E["Error detected"] --> S1{"Data at risk?"}
S1 -->|Yes| T1["Tier 1: STOP<br/>Escalate to human"]
S1 -->|No| S2{"State inconsistent?"}
S2 -->|Yes| T2["Tier 2: Fix + log<br/>Continue work"]
S2 -->|No| T3["Tier 3: Note + workaround<br/>Backlog idea"]
style T1 fill:#ef4444,color:#fff
style T2 fill:#eab308,color:#000
style T3 fill:#22c55e,color:#fff17.2 Escalation
Agents MUST log blockers with the #needs-human tag when:
- Data integrity is at risk (Tier 1 errors)
- A decision exceeds the agent’s authority
- Ambiguous scope could lead to destructive actions
Agents MUST NOT proceed with destructive or irreversible actions when uncertain. When in doubt, stop and ask.