---
name: attempt-ledger
description: Knowledge about attempt tracking and gating patterns for task execution
triggers:
  - relay
  - epic
  - task execution
  - attempt
  - gating
  - retry
---

# Attempt Ledger Pattern

## Purpose

The attempt ledger tracks execution attempts for tasks, enabling:

- **Retry with context:** Each attempt includes previous failure information
- **Gating:** Prevents infinite retry loops when tasks consistently fail
- **Progress persistence:** Resume execution after interruption
- **Receipt tracking:** Structured summaries instead of full transcripts

## Epic Schema

```yaml
# .agents-os/relay/epic.yml
version: 2
id: "20260111-feature-name"
source: "docs/plans/xxx.md"
created_at: "2026-01-11T17:30:00Z"

title: "Feature Name"
description: |
  Brief description of the epic.

tasks:
  T1:
    title: "Create users migration"
    priority: p1
    points: 2
    files:
      - db/migrate/xxx_create_users.rb
    depends_on: []
    acceptance_criteria:  # Generated by relay:init if missing
      - "Migration creates users table with email and password_digest"
      - "Migration is reversible"
      - "Email column has unique index"
```

## Ledger Schema

```yaml
# .agents-os/relay/attempt-ledger.yml
version: 1
epic_id: "20260111-feature-name"
started_at: "2026-01-11T17:30:00Z"

settings:
  max_attempts_per_task: 3
  timeout_minutes: 15

task_status:
  T1: completed
  T2: in_progress
  T3: pending
  T4: blocked

attempts:
  T1:
    - id: 1
      started_at: "..."
      ended_at: "..."
      result: success
      receipt:
        summary: "Created migration and model"
        files_changed: [file1.rb, file2.rb]

  T2:
    - id: 1
      result: failure
      receipt:
        error_category: missing_dependency
        error_summary: "Database not migrated"
        suggestion: "Run db:migrate first"

gated_tasks:
  T5:
    reason: "max_attempts_exceeded"
    gated_at: "..."
```

## Gating Rules

Tasks are gated (blocked from retry) when:

| Condition | Gating Action |
|-----------|---------------|
| `attempts >= max_attempts` | Gate with `max_attempts_exceeded` |
| Same error repeated 2+ times | Gate with `repeated_failure` |
| Quality gate returns BLOCKED | Gate with `quality_gate_blocked` |
| Manual block by user | Gate with `user_blocked` |

## Receipt Structure

### Success Receipt

```yaml
receipt:
  summary: "Brief description of what was done"
  files_changed: [list, of, files]
  quality_gate_verdict: APPROVED
  learning: "Reusable insight from this task"  # Compound learning
  pattern_tags: [yq, shell, quoting]           # For aggregation
```

### Failure Receipt

```yaml
receipt:
  error_category: missing_dependency | code_error | test_failure | quality_gate | cli_error
  error_summary: "What went wrong"
  quality_gate_verdict: NEEDS CHANGES | BLOCKED  # If quality gate failed
  quality_gate_findings: |  # Structured findings for retry context
    ## Finding 1: Missing test coverage
    **Severity:** HIGH
    **File:** app/models/user.rb:15
    **Fix:** Add unit tests for validation
  suggestion: "What to try differently"
  learning: "What was learned from the failure"  # Compound learning
  pattern_tags: [migration, database]            # For aggregation
```

## Compound Learning

Learnings are extracted after each task attempt, aggregated at epic completion, then cleared.

### Per-Task Extraction

After each attempt (success or failure), a lightweight prompt extracts:
- **learning**: One-sentence reusable insight
- **pattern_tags**: Comma-separated tags for grouping

### Epic Completion Flow

When epic completes, the `learning-processor` agent:
1. Reads all learnings from ledger
2. Consolidates similar patterns by semantic meaning
3. Applies frequency thresholds:
   - 1x = Skip (noise)
   - 2x = Emerging (watch)
   - 3x = Recommend
   - 4+ = Strong signal
4. Promotes to AGENTS.md Key Learnings (primary destination)
5. Clears learnings from ledger after promotion

### Why Clear After Promotion?

- Learnings are **temporary working memory**
- AGENTS.md is the **permanent store** (always loaded by Claude)
- Prevents accumulation across epics
- Keeps ledger lean for next epic

## Task Status Flow

```
pending → in_progress → completed
                ↓
            failure → pending (retry)
                ↓
            max_attempts → gated
```

## Integration with Re-anchoring

Each fresh Claude instance receives:

1. **Git state:** Current branch, last commit, uncommitted changes
2. **Epic context:** Title, description, overall progress
3. **Task details:** Files, acceptance criteria, dependencies
4. **Previous receipts:** What was tried, what failed, why

This prevents context drift and ensures each attempt builds on prior learnings.

## Commands

| Command | Purpose |
|---------|---------|
| `/relay:init` | Create epic and ledger from blueprint |
| `/relay:status` | Show progress and gated tasks |
| `/relay:work` | Execute tasks with attempt tracking |

## Defaults

Settings are stored in `attempt-ledger.yml` at init time:

- `max_attempts_per_task: 3` - Retry limit before gating
- `timeout_minutes: 15` - Max execution time per task

Override at runtime with `--max-attempts N` flag.