playbooks

home / skills / sounder25 / google-antigravity-skills-library / 06_error_recovery

06_error_recovery skill

/06_error_recovery

This skill wraps command execution in a self-healing loop, auto-fixes common errors, and retries with structured error context.

npx playbooks add skill sounder25/google-antigravity-skills-library --skill 06_error_recovery

Review the files below or copy the command above to add this skill to your agents.

Files (2)
SKILL.md
1.6 KB
---
name: Error-State Recovery
description: Wraps command execution in a self-healing loop. Uses heuristics to auto-fix common errors (missing deps, locked files) or escalates to the Agent with structured error context.
version: 1.0.0
author: Antigravity Skills Library
created: 2026-01-16
leverage_score: 5/5
---

# SKILL-006: Error-State Recovery

## Overview

Agents often fail due to transient or trivial errors (e.g., missing Python module, locked file, timeout). This skill provides a `Invoke-Recoverable` wrapper that catches these errors, attempts to apply known fixes, and retries the operation.

## Trigger Phrases

- `run with recovery`
- `auto-fix <command>`
- `try hard <command>`

## Inputs

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `--command` | string | Yes | - | The command to execute |
| `--retries` | int | No | 3 | Max retry attempts |
| `--heuristics` | switch | No | True | Enable heuristic auto-fixes (pip, npm, mkdir) |

## Outputs

1. **Success:** Standard output of the command.
2. **Failure:** `ERROR_STATE.json` containing the stack trace, context, and failed fix attempts.

## Supported Heuristics

1. **Python `ModuleNotFoundError`**: Auto-runs `pip install <module>`.
2. **DirectoryNotFound**: Auto-runs `mkdir -p`.
3. **File Locked**: Waits 2s and retries.
4. **CLI Missing**: Checks standard paths for tool (e.g., `forge`, `dotnet`).

## Preconditions

1. PowerShell 7+

## Implementation

See `invoke_recovery.ps1`.

## Integration

```powershell
.\skills\06_error_recovery\invoke_recovery.ps1 -Command "python hunt.py" -Retries 3
```

Overview

This skill provides a recoverable command wrapper that retries failed operations and applies common fixes automatically. It exposes Invoke-Recoverable to run commands with deterministic retry logic, heuristic repairs, and structured error reporting. Designed for PowerShell 7+, it reduces agent interruptions from transient issues like missing packages or locked files.

How this skill works

Invoke-Recoverable executes the provided command and monitors for known error patterns. When a recognized error occurs, it applies a matching heuristic (for example, installing a missing Python package or creating a missing directory), then retries up to the configured limit. If recovery fails, the skill produces a structured ERROR_STATE.json with trace, context, and attempted fixes and can escalate to the agent for manual intervention.

When to use it

  • Running build, test, or scripting tasks that may fail due to environment drift
  • Automating CI/CD steps where transient resource locks or missing deps are common
  • Wrapping third-party CLI calls that may not be present on every host
  • Long-running agent workflows where auto-repair reduces manual restarts
  • Running experiments that should tolerate occasional external failures

Best practices

  • Run on PowerShell 7+ to ensure compatibility with features used by the wrapper
  • Enable heuristics for common environments, but keep manual control for sensitive ops
  • Configure reasonable retry limits to avoid masking persistent faults
  • Combine with pre-action guards to avoid destructive automatic fixes
  • Inspect ERROR_STATE.json when escalation occurs to understand root causes

Example use cases

  • Invoke-Recoverable -Command "python hunt.py" -Retries 3 to auto-install missing Python modules
  • Wrapping a build step that fails due to a missing output directory; the skill will mkdir and retry
  • Running a CLI that occasionally reports file locks; the wrapper waits and retries automatically
  • Batch scripts that call external tools; the skill checks standard install paths and suggests installations on failure
  • Automated agents that should escalate only after structured recovery attempts to preserve human attention

FAQ

What errors does the skill auto-fix?

It targets common transient errors: Python ModuleNotFoundError (auto pip install), missing directories (mkdir -p), simple file locks (wait-and-retry), and absent CLIs (check standard paths and report).

How many retries are performed?

Default is 3 retries; this is configurable with the -Retries parameter to balance resilience and escalation.

What happens if recovery fails?

The skill writes ERROR_STATE.json with the stack trace, context, and attempted fixes, then escalates to the agent for manual handling.