error-handling

name	error-handling
description	Handle failures during spec2cloud execution. Covers sub-agent failures, stuck loops, corrupted state, and test infrastructure failures. Use when encountering errors, retrying failed tasks, or recovering from corrupted state.

Error Handling

Sub-Agent Failure

If a sub-agent fails (crashes, produces invalid output, tests don't pass):

1. Log the failure in audit.log with the error details
2. Retry the same task — the sub-agent gets another attempt
3. On retry, include the previous error as context so the sub-agent can adjust
4. There is no retry limit — loops run indefinitely

Stuck in a Loop

If you detect you're making no progress (same test failing repeatedly, same error recurring):

1. Keep going. Do not stop autonomously.
2. The human is watching. Human Ctrl+C is the escape hatch.
3. Try different approaches on each iteration — don't repeat the exact same fix
4. Log every attempt so the human can diagnose the pattern

Corrupted or Missing State

If state.json is corrupted or contains invalid data:

1. Log the corruption in audit.log
2. Re-assess the project state from the repo itself:
   • Check which spec files exist (specs/prd.md, specs/frd-*.md, specs/features/*.feature)
   • Check which tests exist and whether they pass
   • Check which code exists
   • Check deployment status
3. Reconstruct state.json from the observed repo state
4. Continue from the determined phase

Test Infrastructure Failures

If tests fail to compile or the test runner itself fails (not test assertion failures):

1. Log the infrastructure failure
2. Attempt to fix the test infrastructure (missing dependencies, config issues)
3. Re-run tests
4. If the test infrastructure cannot be fixed, log the blocker and continue attempting