Agent Reflection Pattern: Why Grounded Beats Intrinsic

An agent writes a function, reads it back, and says "looks good to me." It's wrong twice: once about the code, once about its own judgment of the code. Ask that same agent to run the tests instead, read the actual failure, and try again, and the second attempt usually works.

The agent reflection pattern is a loop where an agent critiques its own output and tries again, but the pattern only reliably helps when the critique is grounded in a real external signal (test results, execution output, a linter) rather than the model simply re-reading its own guess. Self-Refine and Reflexion are the two named versions of this loop. The distinction between grounded and intrinsic reflection is the one thing that decides whether the loop fixes bugs or just adds a slower, more confident wrong answer.

Key Takeaways

• Self-Refine loops critique-and-revise within a single attempt; Reflexion carries the critique forward as memory into the next attempt.
• Intrinsic self-correction, the model re-reading its own guess with no outside signal, can decrease accuracy on reasoning tasks (Huang et al., 2023).
• Grounded self-correction, reflecting on test output, execution traces, or a linter, is the version that actually works.
• The graded lab below builds a reflection loop that reads real pytest failures instead of a "does this look right?" pass.
• Reflection is not free. Add it where a task is failure-prone and a real signal exists, not as a default on every agent.

What Is the Agent Reflection Pattern?

The agent reflection pattern is a loop where an agent generates an output, evaluates that output against some standard, and revises it, sometimes more than once, before returning a final answer. Get the mechanism wrong and you'll ship a reflection step that burns tokens on every run and doesn't catch a single real bug, that's the trap the rest of this lesson is about avoiding.

Two specific versions of this loop show up constantly in agent design. Self-Refine has one model act as generator, critic, and reviser inside a single task: produce an answer, generate feedback on that same answer, refine it, and repeat until the feedback says stop. It needs no extra training and no separate model. The original Self-Refine paper tested it across seven tasks. Outputs were preferred over one-shot generation roughly 20% more often.

Reflexion extends the idea across attempts, not just within one. After a failed trial, the agent writes a short verbal reflection ("the tests failed because I mutated the input list instead of copying it") and stores that reflection in memory before trying again. The Reflexion paper reported this lifted GPT-4's score on a coding benchmark from roughly 80% to 91% across repeated attempts. The gain came purely from language-based feedback, no weight updates involved.

Grounded vs. intrinsic reflection, at a glance

Both patterns assume the reasoning skills of chain-of-thought and the reason-act loop from earlier lessons are already in place; reflection is what happens after the agent has already acted and gotten a result back.

The Nuance Almost No Course States: Grounded vs Intrinsic

Every explainer on this topic will tell you an agent can "reflect on its own output." Almost none of them tell you that how it reflects is the whole game.

Intrinsic self-correction means the model checks its own answer using nothing but another pass of its own judgment: same model, same knowledge, no new information entered the room. Grounded self-correction means the model checks its answer against something real and external to its own opinion: a test suite that actually ran, a stack trace, a linter output, a compiler error, a second tool's result.

That finding is the spine of this lesson: reflection is not automatically good. It's good when the thing being reflected on is real. A model re-reading its own guess has no new information, so "reflecting" on it is really just re-rolling the same judgment that produced the guess in the first place, dressed up as a check.

Why Intrinsic Reflection Can Make Things Worse

Ask an agent "does this look right?" about code it just wrote, and it will almost always find something to say, because that's what the prompt asked for. The problem is it has no ground truth to measure against, only its own prior belief restated with more hedging.

Here's the failure mode concretely. An agent writes a function to compute a running median. The logic has a subtle off-by-one: it picks the wrong middle index, so the median comes back one slot away from correct on most inputs.

Ask it "does this look right?" and it typically answers yes, sometimes even praising its own use of sorted(). Nothing forced it to notice the wrong index, because nothing in that prompt gave it a value it hadn't already generated itself.

I've watched this exact intrinsic pass "fix" a bug that didn't exist, rewriting a correctly-initialized variable name because the model decided, with no new evidence, that the original name "looked wrong." The function still failed the same three tests afterward, and now it also had an unrelated cosmetic change to review.

Grounded reflection changes what the model is looking at, not just how carefully it looks. Feed that same function's actual pytest output into the next turn, three failing assertions naming the exact wrong values returned, and the model has something to reason against that isn't just its own prior text. It stops guessing about correctness and starts explaining a specific, real discrepancy. That's the entire mechanical difference between reflection that helps and reflection theater.

Building a Grounded Reflection Loop in Claude Code

A grounded reflection loop has three moving parts, and you can build all three directly in Claude Code: a task, a real check, and a revise step that only fires off the real check's output.

1. Generate. The agent writes a first attempt at the function, based on the spec you give it.
2. Check. The agent runs the actual test command (pytest -q or equivalent) and captures the real stdout, pass/fail counts, and any assertion messages.
3. Reflect and revise. The agent reads that real output, not its own memory of what it wrote, and revises specifically against what failed.

# in Claude Code's terminal, after it writes the first attempt:
pytest test_running_median.py -q

The critical rule: the revise step's prompt should quote the actual failing assertion text, not a summary the model invents. "Tests failed: assert median([1,3,2]) == 2, got 3" is a grounded signal. "I think there might be an issue with sorting" is the model narrating its own suspicion, which is intrinsic reasoning wearing a grounded costume.

This is the same three-part shape as Self-Refine's generate-feedback-refine loop, with one change that makes all the difference: the feedback step is a real command's real output, not the model's own second opinion.

When Reflection Is Worth the Tokens, and When It's Theater

Reflection is not a free upgrade. Every extra critique-and-revise pass costs real tokens and real latency, and on a task the model already gets right on the first try, that cost buys nothing.

Add a reflection step when two things are both true: the task is genuinely failure-prone (multi-step code, a flaky API call, a spec with edge cases), and you have a real signal to reflect on once a plan already executing hits something that fails.

Skip it, or keep it to a single pass, on simple lookups, obvious tool selections, or anything where a wrong first answer is cheap to just retry from scratch.

Watch for the "does this look right?" pattern creeping into agent prompts anywhere in your stack. It reads like diligence, and it's the exact shape Huang et al.'s research showed doesn't reliably help. If a reflection step can't point at something outside the model's own last message, it's decoration, not a correction mechanism.

Your Lab

def running_median(values):
    sorted_vals = sorted(values)
    n = len(sorted_vals)
    mid = n // 2
    if n % 2 == 0:
        return (sorted_vals[mid - 1] + sorted_vals[mid]) / 2
    return sorted_vals[mid]