---
name: reflexion-protocol
description: Engine substrate that injects a self-correction reflection between workflow retries
title: Reflexion — Episodic Failure Memory
category: _meta
status: active
author: system
metadata:
  triggers: []
  priority: 0
---
# Reflexion

This is an **engine substrate** — it's never injected into an agent's prompt.
`WorkflowSupervisor._dispatch_step_with_critique` reads `config/reflexion.yaml`
at the moment a critique scores below threshold, fires a small LLM call to
produce a verbal self-correction ("Next time: X"), and prepends the
accumulated reflections into the NEXT revision's task.

Inspired by Shinn et al. 2023 (arxiv:2303.11366). Re-implementation only —
no code imported from the reflexion reference repo.

## What this skill owns

- **Enable flag**: reflexion is ON by default. Flip `enabled: false` to fall
  back to the pre-reflexion critique loop (one-shot revision without
  between-try reflection).
- **Buffer depth**: `max_reflections_per_step` controls how many reflections
  accumulate per (agent_key, step_id) tuple. Defaults to 3 — enough for a
  step that repeats a shape of mistake without drowning the next prompt.
- **Budget**: `model_tier` (default `fast`), `max_tokens` (220),
  `timeout_seconds` (30). Reflection is a quality boost, not a safety
  rail — keep the budget tight so a stuck LLM doesn't stretch the
  supervisor's revision loop.
- **Prompt template**: `prompt` is a Python format string with
  `{task}`, `{output}`, `{critique}`, `{score}` placeholders. Missing or
  malformed placeholders fall through to the fallback prompt.

## Fail-open guarantee

Every failure mode in the reflection pipeline (LLM timeout, network error,
bad template, parse failure, empty response) returns `None` and the
revision loop continues exactly as it did pre-reflexion. The critique
flow + revision dispatch never block on this.

## What this skill does NOT own

- Which workflows use reflection — that's opt-in via `WorkflowStep.critique`
  (a non-None `CritiqueSpec` on a step means the revision loop runs, and
  reflexion runs inside it). Steps without a critique spec don't reflect.
- The critique protocol itself — that's owned by the sibling
  `critique-protocol` skill.
- Cross-session persistence — the buffer is bounded and per-execution.
  Reflections from Monday's run don't leak into Tuesday's.

## Auditability

Every reflection that successfully generates appends a `reflexion` entry to
`execution.supervisor_log` with `{step, agent, score_before, reflection,
timestamp}`. Skipped / failed reflections log at DEBUG only — no spam in
the supervisor trail when the path no-ops.