Forem: Greg Smethells

Your Decision Log Is an Archaeological Site

Greg Smethells — Wed, 25 Mar 2026 02:25:47 +0000

I was building a small project with an AI coding agent when I realized my architecture documentation was failing both of us. The agent would start each session by reading through a growing pile of decision records, trying to reconstruct what was still true. I was doing the same thing every time I came back after a week away.

The documentation existed. Nobody was getting value from it.

ADRs Solve the Wrong Problem

Architecture Decision Records are append-only by convention. When a decision changes, you don't update the old record — you write a new one that supersedes it. This sounds principled. In practice, it means your docs/decisions/ directory grows forever and the only way to understand the current state of the architecture is to read 40 files and mentally diff them against each other.

The decisions that still matter? Maybe five of them. The other 35 are historical noise — half-abandoned ideas, constraints that evaporated when you switched libraries, debates that got resolved and then relitigated and then resolved again. Nobody reads them. I stopped reading them.

The directory becomes an archaeological site when what you actually needed was a sign on the door.

What You Actually Need Depends On What You're Doing

When do you actually reach for decision documentation?

When you're orienting to a project — coming back after two weeks, or handing context to someone else — you need the 5–10 decisions that explain why the code is shaped the way it is right now. Not the history. The current state.

When you're editing a specific file — you want the relevant context right there, not in a document you have to go find. If there's a non-obvious reason a function is structured a certain way, that reason belongs in a comment next to the function, not in a separate record you have to cross-reference.

When a decision changes — you want to update the record. Not append to it forever.

ADRs optimize for auditability at the expense of usability. That's the wrong tradeoff for a small team or a solo project.

Three Layers That Actually Work

DESIGN.md in the repo root. Three sections only: Architecture, Decisions, Constraints. Hard cap at 100 lines. When a decision changes, edit it in place. When the file fills up, curate — remove what's no longer load-bearing.

Here's what a few entries look like in practice:

## Decisions

- **Redis for score caching, not DB reads**: Scores change every 5 min via worker;
  cache hit target is <50ms. DB fallback on miss.
- **Async SQLAlchemy throughout**: All DB access is async to avoid blocking the
  event loop under concurrent probe runs. Do not add sync sessions.
- **No JWT / no OAuth**: API keys only. Email-verified at creation. Keeps auth
  surface small and agent-friendly.

Each entry is one or two lines: the decision, and the reason it's still load-bearing. If you can't summarize it that briefly, it probably belongs in a comment in the code instead.

Inline comments. Local decision context belongs in the code, next to the thing it explains. # XXX: for non-obvious logic or important implementation notes. If a caching layer exists in a weird place, or a function is structured in a way that looks wrong but isn't — that reason lives in a comment, not in a document.

Git history. The actual audit trail. Commit messages explain why a change was made. git blame ties a decision to the exact code change that enacted it. The history is embedded in the thing it describes, not floating in a separate file that may or may not stay in sync.

The Cap Is the Whole Point

Without the 100-line limit, DESIGN.md becomes the same problem as an ADR directory, just collapsed into a single file. The cap is the forcing function. Every time the file gets full, you have to decide what's still worth front-and-centering versus what's just history. That act of deciding is where the value is. Accumulation is easy. Curation is the work.

What You're Giving Up

You can't reconstruct the full decision history from DESIGN.md alone. If you need to know exactly when a call was made and why, it won't be there.

But that's what git is for — and git is a better place for it. The history is tied to the actual code change, not a separate document written after the fact. git log -p tells you more about what happened and why than any ADR, as long as you write decent commit messages.

The Two-Minute Test

Here's what crystallized this for me: Claude Code reads DESIGN.md at the start of every session to orient itself before touching any code. An AI agent needs to understand the shape of a project fast, or it makes wrong turns. So does a human coming back after a week away. So does a new hire on day one.

If someone can read DESIGN.md and understand why the code is shaped the way it is in two minutes — not the history, not every tradeoff ever considered, just the decisions that still govern the code today — you've won.

That's the test. A directory full of ADRs rarely passes it.

TL;DR

ADR directories are append-only and grow forever; after a year you're reading 40 files to find the 5 decisions that still matter.
DESIGN.md with a 100-line hard cap keeps only what's currently true — when it fills up, you're forced to decide what to keep.
Git history is your audit trail; it's already tied to the code, which is where it belongs.

REEL: A Proper Name for the Autonomous Agent Loop

Greg Smethells — Sat, 07 Mar 2026 08:06:58 +0000

There is a pattern spreading through the AI coding community. You write a spec, an outer loop spawns fresh AI sessions for each task, acceptance checks gate progress, and the codebase accumulates working code — all without a human in the loop. The pattern works. But it is stuck with a name borrowed from a cartoon character.

The "Ralph Wiggum loop" is fun, but it does not belong in a design document. The pattern deserves a proper name — one that works as a verb, a noun, and a proper acronym. That name is REEL.

What is a REEL?

REEL stands for Review Evaluated Engineering Loop. It describes any autonomous coding workflow with these five characteristics:

Spec in — a structured specification defines the tasks
Fresh session per task — each task gets a clean context window (no accumulated drift)
Acceptance check — every task must pass a defined verification (tests, linters, reviews)
State on disk — progress is tracked in files, not in memory
Iterate until done — failed tasks are retried, passing tasks feed context to the next

The key insight: the codebase is the memory, not the context window. Each fresh session reads the current state of the code, does its work, and writes results back to disk. The context window is disposable. The repo is permanent.

This makes REELs fundamentally different from long-running agent sessions. There is no context window to exhaust, no degradation over time, no catastrophic forgetting. Each task starts clean and inherits progress through the only artifact that matters — the code itself.

Why "REEL"?

The acronym earns every letter. Review Evaluated Engineering Loop — "review" because every task is review-gated before it passes; "evaluated" because acceptance checks evaluate each result; "engineering" because the output is engineered software, not just generated code; "loop" because it iterates until the spec is satisfied.

It works as a verb. "Reel in the feature" is natural English for persistent, iterative effort. You cast your line (write a spec), reel it in (iterate through tasks), and land the catch (working code). The fishing metaphor maps perfectly: patience, persistence, incremental progress.

It works as a noun. "I ran a REEL on the auth refactor" — clean and unambiguous.

It sounds like "real." The near-homophone is a feature, not an accident. When the REEL finishes, the spec becomes real. Working code, passing tests, reviewed and linted — real software, built autonomously.

Compare to RAG. Nobody says "Retrieval-Augmented Generation" in conversation — they say RAG. The acronym is the term. REEL works the same way: short, memorable, and precise enough that the expansion only matters the first time you hear it.

How It Works

A REEL follows this flow:

Spec directory (md/json/feature — any mix)
  |
  v
Parse tasks + dependencies + namespaces
  |
  v
Verification pass (run acceptance checks on existing code)
  |
  v
For each eligible task:
  |-> Create git worktree (isolated branch per task)
  |-> Spawn fresh AI session (with progress context)
  |-> Execute task in worktree
  |-> Run acceptance check
  |-> Run lint gate (fresh session)
  |-> Run review gate (fresh session)
  |-> Merge worktree into feature branch
  |-> Record progress
  |-> Update state
  |
  v
Next task (or retry on failure with fresh worktree)
  |
  v
Advance spec to next pipeline stage

Worktree Isolation

Each task gets its own git worktree branched from the feature branch. The main worktree is the orchestration desk — state, progress, and logs live there, untouched by task work. When a task passes, its worktree merges back into the feature branch. When a task fails, the worktree is discarded and a fresh one is created for the retry, branched from the latest feature branch state (which includes all previously merged work).

This eliminates an entire class of problems: cross-task file contamination, git add -A staging another task's files, and concurrent edits clobbering each other.

Three Quality Gates

Every task must pass three gates before it is marked as done:

Acceptance check — the spec-defined verification command (tests, build, custom script)
Lint gate — a fresh AI session runs language-specific linters on changed files
Review gate — a fresh AI session runs a code review, blocking on Minor or higher severity findings

Each gate runs in its own session with its own budget. The lint and review gates can be disabled with --no-lint and --no-review for speed.

State Management

Per-task progress (pass/fail, attempt counts, errors) is tracked in .reel/state.json — spec files are never modified. You can abort at any time — SIGINT/SIGTERM traps save state — and resume exactly where you left off. When all tasks in a spec pass, the spec file advances to the next pipeline stage.

Progress Accumulation

After each task passes, a summary (description + files changed) is appended to .reel/progress.txt. Subsequent tasks receive this context in their prompt, preventing duplication across sessions without polluting the context window.

Safety Controls

Max iterations: 20 total iterations across all tasks (configurable)
Per-task budget: $1.00 default spend cap per task
Retry limit: 3 attempts per task before marking as failed
Circuit breaker: 3 consecutive failures halt the entire run
Lock file: prevents concurrent runs on the same spec
Graceful abort: SIGINT/SIGTERM traps save state for resume

Pipeline Stages

REEL organizes specs into a pipeline. The filesystem is the board — a spec file's directory determines its stage:

spec/
  todo/       — Approved backlog, ready to work
  design/     — In design phase
  inflight/   — Being implemented (REEL core behavior)
  review/     — In review phase
  active/     — Done, actively enforced specification
  archived/   — Historical, out of flow

When all tasks in a spec pass, REEL advances it to the next stage via git mv. The transition is atomic and auditable — it is just a commit.

Spec Formats

A REEL is driven by structured specs in three formats — use whichever fits your workflow. Mix formats freely within the same pipeline directory.

Gherkin (.feature files) — recommended for larger specs:

Each Scenario becomes a task. Tag-based metadata provides stable IDs, dependencies, and acceptance overrides:

Feature: Auth Refactor

  @id:a1b2c3d4
  @acceptance:pytest tests/test_session.py
  Scenario: Extract session manager
    Given route handlers contain inline session logic
    When the session manager module is created
    Then all session operations are delegated to the new module

  @id:e5f6a7b8
  @depends-on:a1b2c3d4
  @acceptance:pytest tests/test_refresh.py
  Scenario: Add token refresh
    Given the session manager exists
    When a token expires during a request
    Then the token is refreshed automatically

IDs are 8-character lowercase hex (truncated UUID v4) — globally unique and stable across refactors. Generate them with reel --generate-id [spec-dir], which scans existing IDs to prevent collisions. Feature files without @id: tags fall back to auto-generated sequential IDs.

Markdown (heading-per-task):

## a1b2c3d4: Extract session manager

Move session handling out of route handlers into a dedicated module.

**Acceptance:** `pytest tests/test_session.py`

## e5f6a7b8: Add token refresh

Implement automatic token refresh in the session manager.

**Acceptance:** `pytest tests/test_refresh.py`
**Depends on:** a1b2c3d4

JSON (structured):

{
  "name": "Auth Refactor",
  "tasks": [
    { "id": "a1b2c3d4", "description": "Extract session manager", "acceptance": "pytest tests/test_session.py" },
    { "id": "e5f6a7b8", "description": "Add token refresh", "acceptance": "pytest tests/test_refresh.py", "depends_on": ["a1b2c3d4"] }
  ]
}

Automatic namespacing: In directory mode, each file's tasks are prefixed with the file stem to prevent ID collisions. spec/inflight/auth.md produces auth:a1b2c3d4, auth:e5f6a7b8. Within-file dependencies use bare IDs (auto-resolved); cross-file dependencies use qualified IDs like auth:a1b2c3d4.

History

Geoffrey Huntley identified the autonomous agent loop pattern in mid-2025, demonstrating that writing structured specs and feeding them to fresh AI sessions produced better results than marathon single-session coding.

The community adopted the pattern enthusiastically in late 2025, calling it the "Ralph Wiggum loop" — a pop-culture name that went viral but lacks technical precision.

REEL provides a culturally agnostic, technically precise replacement. The pattern itself is tool-agnostic — it works with any AI coding CLI that supports non-interactive mode. Its name should be too.

The pattern has earned a real name. Next time you describe it, try calling it a REEL — and see if the conversation gets a little clearer.