pi-skills/.pi/skills/goal-driven-loop/references/error-handling.md

Error Handling Reference

Detailed retry strategy, exception classification, and recovery rules for the goal-driven-loop skill.

Retry Strategy (Automatic, No Human Intervention)

All recoverable exceptions use exponential backoff. Counter is per-iteration — resets at the start of each new iteration.

Parameter	Value
Max retries	10 per iteration
Initial delay	30s
Backoff factor	×2
Max delay	300s (5min)

Backoff sequence:

Retry	Delay	Cumulative
1	30s	0.5min
2	60s	1.5min
3	120s	3.5min
4	240s	7.5min
5	300s	12.5min
6	300s	17.5min
7	300s	22.5min
8	300s	27.5min
9	300s	32.5min
10	300s	37.5min

Formula: delay = min(30 * 2^(retry-1), 300) seconds.

Execution: Before retry, run bash -c "sleep <delay> && echo done" with timeout parameter set to delay + 30. If sleep is interrupted, treat as tool failure, enter retry.

After 10 retries exhausted: status = blocked, write Blocked section to GOAL.md, extension auto-attempts alternative approach. If still blocked after auto-attempt, then notify user.

Exception Classification

Exception	Detection signal	Recoverable?	Response
Tool execution failure	bash returns non-zero exit	Yes	Exponential backoff retry
LLM API exception	subagent timeout/error	Yes	Exponential backoff retry
Context tension	Extension detects getContextUsage() > 0.8	No	Extension auto-saves state, injects continuation directive
User interruption	User sends new message mid-loop	No	Extension auto-pauses, responds, resumes on next trigger
Stale state	GOAL.md exists with status = in-progress	No	Extension prompts: continue / replace / abandon (10s timeout → continue)

Stagnation Detection

Both signals must be present:

1. Acceptance criteria passing count unchanged for 3 consecutive iterations, AND
2. Progress Log last 3 iterations contain no progress keywords (found / fixed / implemented / added / refactored / verified)

Only both conditions together trigger stagnation. Extension auto-injects strategy-change prompt. After 2 consecutive auto-recoveries with no progress, extension notifies user.

Continuation Prompt Format (Fixed)

When context is tight, output exactly this format:

🔄 目标状态已保存至 .agents/goal/GOAL.md
当前进度：X/Y criteria 通过，第 N 轮迭代。

The extension injects the full state summary on every before_agent_start, so the next prompt automatically re-loads the goal.

Red Flags — These Do NOT Count as Completion

• "LLM call failed, goal should be considered complete" → retry or blocked
• "Tests don't run but code looks fine" → must have test evidence
• "Context full, let me summarize" → save state, extension auto-injects continuation, do not declare done
• "Too many retries, skip this criterion" → exhausted retries → blocked, do not skip
• "This criterion is too hard to verify, skip it" → agent may auto-rewrite, logged as material change
• "All criteria basically met, close enough" → each criterion must have explicit pass evidence
• "Deslop pass would take too long, skip" → deslop failure does not block, but agent should still attempt it