# How to Implement the Recovery System for Automatic Failure Handling in aios-core

> Implement aios-core's Recovery System for automatic failure handling. Log task executions, manage retries and rollbacks, and integrate with CLI tools.

- Repository: [SynkraAI/aios-core](https://github.com/synkraai/aios-core)
- Tags: how-to-guide
- Published: 2026-02-16

---

**The Recovery System in aios-core provides automatic failure handling through the `RecoveryTracker` class, which records every sub-task execution to JSON-backed attempt files, supports programmatic retries and rollbacks, and exposes a CLI for agent integration.**

The **Recovery System** (Epic 5 of the Autonomous Development Engine) is a critical infrastructure component in the [SynkraAI/aios-core](https://github.com/SynkraAI/aios-core) repository. It enables autonomous agents to track execution attempts, handle failures gracefully, and maintain auditable histories of every sub-task. This guide explains how to implement the Recovery System using the `RecoveryTracker` class and its associated CLI tools.

## Understanding the aios-core Recovery System Architecture

The Recovery System is built around three core pillars: a programmatic API, strict schema validation, and a command-line interface for agent interaction.

### Core Components

The **`RecoveryTracker`** class, defined in [`.aios-core/infrastructure/scripts/recovery-tracker.js`](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/infrastructure/scripts/recovery-tracker.js), serves as the primary API. It handles loading attempt histories, validating data against the `ATTEMPTS_SCHEMA` (lines 83-116), and persisting updates to disk. The schema enforces required fields including `attemptNumber`, `status`, `startTime`, and `approach`.

The **CLI entry point** (lines 442-629) parses commands such as `start`, `complete`, `abandon`, `history`, and `summary`, forwarding them to the appropriate `RecoveryTracker` methods.

### File Structure and Storage

Each story receives isolated storage under `docs/stories/<story-id>/recovery/`. The tracker auto-creates this directory on first use. Individual sub-tasks maintain separate JSON files named `subtask-<id>.json` (`AC6`), ensuring that concurrent work on different sub-tasks does not create write conflicts.

## Implementing the RecoveryTracker Class

To integrate automatic failure handling into your application, instantiate the tracker and invoke its lifecycle methods at appropriate execution points.

### Initializing the Tracker

Create a tracker instance by specifying the story identifier. The constructor automatically resolves paths based on the centralized `CONFIG` object (lines 50-58).

```javascript
const { RecoveryTracker } = require('./.aios-core/infrastructure/scripts/recovery-tracker');

// Initialize for a specific story
const tracker = new RecoveryTracker({ storyId: 'STORY-42' });

```

### Starting and Completing Attempts

Use `startAttempt()` to record the beginning of a sub-task execution. This method auto-increments attempt numbers (`AC7`) and timestamps the entry.

```javascript
// Start tracking sub-task 2.1
const attempt = tracker.startAttempt('2.1', {
  approach: 'Refactor state handling with zustand middleware',
  changes: ['src/store.ts', 'src/components/Widget.ts'],
  notes: 'First try with immer middleware',
});

console.log('Started attempt #: ', attempt.number);

```

When execution finishes, call `completeAttempt()` with the outcome. For failures, include error details to support downstream analysis.

```javascript
// Record a failed attempt
tracker.completeAttempt('2.1', {
  success: false,
  error: 'TypeError: persist is not a function',
  notes: 'Missing export from zustand-persist',
});

// Record a successful attempt
tracker.completeAttempt('2.1', {
  success: true,
  notes: 'All tests passing',
});

```

### Handling Failures and Rollbacks

For unrecoverable errors, invoke `abandonAttempt()` to mark the sub-task as abandoned. This status triggers rollback procedures in the ADE pipeline and prevents further automatic retries.

```javascript
// Abandon the current approach
tracker.abandonAttempt('2.1', {
  reason: 'Architecture incompatible with existing state shape',
  rollbackTarget: '2.0',
});

```

## Using the Recovery System CLI

Agents and automation scripts interact with the Recovery System through the CLI wrapper, enabling `*track-attempt` and `*rollback` commands.

### Starting a New Attempt

Execute the `start` command with the story ID, sub-task ID, and metadata flags.

```bash
node .aios-core/infrastructure/scripts/recovery-tracker.js start STORY-42 2.1 \
  --approach "Add optimistic UI updates" \
  --changes "src/ui.jsx,src/api.js" \
  --notes "Will need to add loading flag"

```

### Recording Success or Failure

Update the attempt status using the `complete` command with either `--success` or `--fail`.

```bash

# Mark as successful

node .aios-core/infrastructure/scripts/recovery-tracker.js complete STORY-42 2.1 --success

# Mark as failed with error details

node .aios-core/infrastructure/scripts/recovery-tracker.js complete STORY-42 2.1 \
  --fail \
  --error "ReferenceError: apiClient is undefined"

```

### Generating Reports

Retrieve human-readable history or story-wide summaries using the `history` and `summary` commands.

```bash

# View sub-task specific history

node .aios-core/infrastructure/scripts/recovery-tracker.js history STORY-42 2.1

# View story-wide recovery summary

node .aios-core/infrastructure/scripts/recovery-tracker.js summary STORY-42

```

The `generateReport()` method (lines 778-834) produces markdown-styled output suitable for agent consumption and documentation.

## Validating Recovery Data with JSON Schema

The Recovery System enforces data integrity through the `ATTEMPTS_SCHEMA` constant. To export the schema for external validation tools or documentation:

```bash
node .aios-core/infrastructure/scripts/recovery-tracker.js schema > attempts-schema.json

```

The schema defines required properties including `attemptNumber`, `status` (enum: `['in-progress', 'completed', 'abandoned']`), `startTime`, `endTime`, and nested `approach` objects. Runtime validation occurs in `RecoveryTracker.validateData()` (lines 232-267), ensuring corrupted attempt files cannot propagate through the ADE pipeline.

## Integrating Recovery Tracking into the ADE Pipeline

The Recovery System serves as the failure-handling backbone of the Autonomous Development Engine (ADE). According to the [ADE Guide](https://github.com/SynkraAI/aios-core/blob/main/docs/guides/ade-guide.md#epic-5-recovery-system), agents invoke recovery commands through standardized terminal protocols:

- **`*track-attempt`** – Maps to the CLI `start` and `complete` commands.
- **`*rollback`** – Maps to the CLI `abandon` command, triggering the rollback procedure.

The Execution Engine can programmatically instantiate `RecoveryTracker` to record attempts without shelling out to the CLI, reducing overhead for high-frequency operations. Recovery data feeds into Epic 6 (QA Evolution) for test result correlation and Epic 7 (Memory Layer) for long-term pattern analysis.

## Summary

- The **Recovery System** in aios-core provides automatic failure handling through JSON-backed attempt tracking, implemented in [`.aios-core/infrastructure/scripts/recovery-tracker.js`](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/infrastructure/scripts/recovery-tracker.js).
- Use the **`RecoveryTracker`** class programmatically with `startAttempt()`, `completeAttempt()`, and `abandonAttempt()` to manage sub-task lifecycles.
- Invoke the **CLI** for agent integration using commands like `start`, `complete`, `history`, and `summary`.
- All attempt data is stored under `docs/stories/<story-id>/recovery/subtask-<id>.json` with strict schema validation via `ATTEMPTS_SCHEMA`.
- The system integrates with the ADE pipeline through standardized commands (`*track-attempt`, `*rollback`) and supports downstream analysis for QA Evolution and Memory Layer epics.

## Frequently Asked Questions

### Where is the RecoveryTracker class defined in aios-core?

The `RecoveryTracker` class is defined in [`.aios-core/infrastructure/scripts/recovery-tracker.js`](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/infrastructure/scripts/recovery-tracker.js) (lines 118-230). This file also exports the `ATTEMPTS_SCHEMA` constant and provides the CLI entry point, making it the single source of truth for recovery functionality in the framework.

### How does the Recovery System handle automatic retries?

The Recovery System tracks each execution as a distinct attempt with an auto-incremented `attemptNumber` (`AC7`). While the core tracker does not automatically re-execute failed code, it maintains the complete history of failures under `docs/stories/<story-id>/recovery/`. Agents or the Execution Engine can query this history via `tracker.getAttemptHistory()` to decide whether to retry based on failure patterns, ensuring intelligent retry logic rather than blind repetition.

### Can I use the Recovery System outside of the ADE pipeline?

Yes. While designed for the Autonomous Development Engine, the `RecoveryTracker` class is a standalone module with no hard dependencies on other ADE components. You can require it in any Node.js application to track arbitrary task attempts by instantiating it with a custom `storyId`. The CLI also functions independently, allowing integration into non-ADE automation scripts or manual developer workflows.

### What file format does the Recovery System use for attempt history?

The Recovery System uses **JSON** files with a strict schema defined by `ATTEMPTS_SCHEMA`. Each sub-task receives its own file named `subtask-<id>.json` stored under `docs/stories/<story-id>/recovery/`. These files contain an array of attempt objects with properties including `attemptNumber`, `status` (enum: `in-progress`, `completed`, `abandoned`), `startTime`, `endTime`, `approach`, `changes`, and optional `error` messages.