agent-ops-recovery

name	agent-ops-recovery
description	Handle failures and errors during workflow. Use when build breaks, tests fail unexpectedly, or agent gets stuck. Semi-automatic recovery with user confirmation for destructive actions.
category	git
invokes	["agent-ops-state","agent-ops-git","agent-ops-tasks","agent-ops-debugging"]
invoked_by	[]
state_files	{"read":["constitution.md","baseline.md","focus.md","issues/*.md"],"write":["focus.md","issues/*.md","memory.md"]}

Error Recovery workflow

Trigger conditions

Use this skill when:

• Build/lint fails unexpectedly after agent changes
• Tests fail that were passing in baseline
• Agent encounters ambiguity it cannot resolve
• Implementation is stuck or going in circles

Recovery procedure

Step 1: Diagnose (invoke debugging)

For non-trivial failures, invoke agent-ops-debugging:

1. Apply systematic debugging process:
   • Reproduce the issue consistently
   • Define expected vs actual behavior
   • Form hypothesis about root cause
2. Use debugging output to inform recovery decision
3. If root cause unclear after initial analysis, continue debugging before recovery

Step 2: Assess rollback options

• Option A: Fix forward — issue is minor, can be resolved quickly
• Option B: Partial rollback — revert specific file(s) to last good state
• Option C: Full rollback — revert all agent changes since checkpoint
• Option D: Escalate — document the issue, mark task blocked, ask user

Step 3: Propose action

Present options to user with:

• What will be reverted/changed
• Risk assessment
• Recommendation

Step 4: Execute (with confirmation)

• For non-destructive actions (fix forward): proceed
• For destructive actions (rollback): ask user first
• Update .agent/focus.md with recovery action taken

Destructive actions (require confirmation)

• git reset
• git checkout -- <file> (discard changes)
• git revert
• Deleting files
• Overwriting files with previous versions

Non-destructive actions (can proceed)

• git stash
• Reading files
• Running diagnostics
• Updating focus/tasks with findings

Post-recovery

1. Update .agent/focus.md with what happened
2. Invoke agent-ops-tasks to create issue for root cause investigation
3. Update .agent/memory.md with "pitfall to avoid" if applicable
4. Re-run baseline comparison before continuing

Issue Discovery After Recovery

After recovery, invoke agent-ops-tasks discovery procedure:

1. Create issue for the incident:

   📋 Recovery completed. Create issue to track root cause?
   
   Suggested:
   - [BUG] Investigate: {description of what failed}
     - What happened: {failure description}
     - Recovery action: {what was done}
     - Root cause: TBD
   
   Create this issue? [Y]es / [N]o
   

2. If pattern detected, create prevention issue:

   This failure pattern has occurred before. Create improvement issue?
   
   - [CHORE] Add validation to prevent {failure type}
   - [TEST] Add regression test for {scenario}
   
   Create these? [A]ll / [S]elect / [N]one
   

3. After creating issues:

   Created {N} issues for tracking. What's next?
   
   1. Investigate root cause now (BUG-0024@abc123)
   2. Continue with original work (defer investigation)
   3. Review recovery actions