AAR Loop

AAR with folder-based lessons, auto-trigger for all tasks, US Army 4-question method for AI agents.

A human-run version of the Army's After Action Review, pointed at an AI agent's own session. Ask the same 4 questions the Army asks after every rotation at the National Training Center, answer them honestly about what the agent just did, and write down what changed as a result. Do this every session and the agent accumulates real, checkable lessons instead of starting from zero each time.

Where this comes from

The US Army formalized the After Action Review in the mid-1970s, after Vietnam, as a structured debrief for training exercises. Became official doctrine in 1993 with field manual TC 25-20. Fifty years of practice on one method because it works on a simple mechanism: separate the debrief from blame, and the same mistake gets caught before it repeats.

This skill borrows that mechanism for AI agent sessions. Research parallel: Reflexion (Shinn et al., 2023) showed agents that generate a verbal self-reflection after a failed attempt and carry that reflection into the next attempt outperform agents with no memory of what went wrong.

The 4 questions

Ask all four, in order, about the task or session just finished. Answer briefly and honestly.

1. What was supposed to happen? The plan, the instruction, the expected outcome.
2. What actually happened? The real outcome, including partial completions, errors, silent failures.
3. Why was there a difference? The actual mechanism, not a mood. "The API caps batch writes at 100" is a why. "I should have been more careful" is not.
4. What do we do the same or differently next time? The concrete rule that would have prevented the gap.

If the answer to question 3 is "nothing went wrong, this worked exactly as planned," that is a valid AAR. Write down what worked as a lesson too.

Folder Structure

Lessons are stored as individual files for scalability:

text

workspace/
├── LESSONS.md              # Index file (like MEMORY.md)
└── lessons/
    ├── 2026-07-31_aar-skill-install.md
    ├── 2026-07-30_thinking-leak.md
    └── 2026-07-29_config-override.md

Individual Lesson File Format

Each lesson file in lessons/ folder:

markdown

---
date: 2026-07-31
tags: [config, bug]
task: "Fix thinking leak"
fix_applied: true
---

## What Was Supposed To Happen?
[Expected outcome]

## What Actually Happened?
[Actual outcome]

## Why Was There A Difference?
[Root cause analysis]

## What Can We Learn?
[Concrete, checkable lesson]

## Fix Plan (if applicable)
**Target:** `AGENTS.md`
**Edit:** Add rule about agent-level config override

Index File (LESSONS.md)

LESSONS.md serves as an index (like MEMORY.md):

markdown

# Lessons Index

## 2026-07-31 — AAR Skill Installation
- Task: Install AAR skill dari GitHub
- Lesson: Skill dari GitHub perlu manual install, ClawHub belum ada
- Detail: [lessons/2026-07-31_aar-skill-install.md](lessons/2026-07-31_aar-skill-install.md)
- Tags: skill, install

## 2026-07-30 — Thinking Leak Fix
- Task: Fix internal monolog bocor ke chat
- Lesson: Agent-level override bisa nge-bypass global config
- Detail: [lessons/2026-07-30_thinking-leak.md](lessons/2026-07-30_thinking-leak.md)
- Tags: config, bug

Auto-Trigger for ALL Tasks

AAR runs after EVERY task, not just big ones:

Task Size	AAR Format	Example
Small (< 5 min, read-only, simple edits)	1-sentence quick capture	"Lesson: Config override di agent-level bisa bypass global setting"
Medium (multi-step, file edits, deployments)	Full AAR with fix plan	Complete 4-question analysis
Large (infra, production, client-facing, irreversible)	Full AAR + verifier review	Complete analysis + second pair of eyes

Trigger: After Verify phase in RPDV workflow.

Extracting a concrete lesson

Question 4 only pays off if the lesson is specific enough to check later. Test every lesson: could a different agent, six months from now, read this line and know exactly what to do or not do?

Concrete, checkable (ship these):

• "Batch size over 100 rows fails with silent timeout; cap batch writes at 100."
• "Agent-level config override bypasses global setting; always check both levels."

Vague, do not ship:

• "Write better code."
• "Be more careful with APIs."

Using the script

bash

# Create new lesson
python3 scripts/append_lesson.py \
  --task "Task name" \
  --expected "Expected outcome" \
  --actual "Actual outcome" \
  --why "Root cause" \
  --lesson "Lesson learned" \
  --tags "tag1,tag2" \
  --fix-target "file.md" \
  --fix-edit "exact edit"

# List all lessons
python3 scripts/append_lesson.py --list

# Search lessons
python3 scripts/append_lesson.py --search "keyword"

The script:

1. Creates individual lesson file in lessons/ folder
2. Auto-updates LESSONS.md index
3. Prevents duplicate entries

Workflow

1. Finish the task.
2. Ask and answer the 4 questions (out loud or in thinking).
3. Extract 1-3 concrete, checkable lessons.
4. For each lesson, decide if it needs a durable fix. If yes, write fix plan.
5. Run scripts/append_lesson.py to create lesson file + update index.
6. Report back: the 4 answers, fix plan status, lesson(s) written.

Rules

• Every lesson names a specific tool, command, number, file, or condition.
• Every fix plan names an exact target file and exact edit.
• Never apply a fix plan without approval, unless user said "apply" or "fix it".
• Run AAR on ALL tasks, not just big ones. Quick capture for small tasks.
• Check for duplicates before writing.
• Lessons folder structure: lessons/YYYY-MM-DD_{topic-slug}.md
• Index file: LESSONS.md (like MEMORY.md)

Loading lessons next session

Two ways to make lessons automatic:

1. Project-local: AGENTS.md has pointer: "Read LESSONS.md before starting work."
2. On demand: Before similar task, run python3 scripts/append_lesson.py --search <keyword>

A lessons file nobody loads is a diary, not a loop. The loop only closes when the next session actually reads it before acting.