Chapter 7: Reflection and evaluation: How your agent audits and learns from itself
The chapter introduction shows why useful fixes to individual agent failures need evaluation across runs to determine whether the system is improving.
After this chapter you will be able to
- Local fixes and system improvement. Explain why a reflection pass that fixes the current failure cannot, by itself, show that an agent is improving overall. Describe how the accumulated safeguards in the example made builds more stable but also slower and burdened by overlapping or conflicting rules.
- Reflection design questions. Explain reflection as feedback permitted to change something, and state the three production-design questions: what the feedback can see, when the result will be known, and what the agent may change.
- Evidence matched to claims. Justify why evidence for a reflection-driven change must match the claim being made, using the contrast between a unit test and the long-term cost of many patches.
- Limits of unguided reconsideration. Explain why asking an LLM to reconsider an answer without new evidence is not a reliable error check.
- Evidence-grounded verification. Describe why reflection is more dependable when the reviewer can check an artifact against evidence, and give a section example of such a check.
- Independent review perspective. Distinguish a genuinely useful Critic from merely adding another model or model family.
- Separate production and review. Explain how a Generator creates an artifact, a Critic reviews it against stated criteria and available evidence, and the Generator revises that same artifact or delivers it when review is satisfied.
- Critic evidence and review contract. Describe what must be specified for a useful review: the artifact version, the Critic's criteria and evidence, permitted verdicts, and a stop policy. Explain why giving the Critic the Generator's same assumptions and evidence can preserve a blind spot.
- A Different Review Inquiry. Explain why a Critic must do more than repeat the Generator's reasoning, using the SQL example to show how a different question or evidence can expose a shared assumption.
- Evidence-Bounded Feedback Scope. Describe feedback scope and distinguish what syntax checks, execution, expected-row tests, and domain review can establish. Explain why a human reviewer also needs a focused question and relevant evidence.
- Critic contract priority. Explain why defining a useful Critic contract matters more than choosing whether the Critic is a model, tool, or person.
- Bounded critique iterations. Describe what to record during critique and revision, when to stop iterating, and why to preserve the best artifact seen so far.
- Traceable independent review evidence. Explain how review findings remain traceable and how evidence is collected separately from the Critic.
- Evidence based best version. Explain how the bounded implementation handles iterations and chooses which artifact version to preserve.
- Independent evidence-grounded critique. Explain why a Critic needs a different review path from the Generator and why its findings must be tied to criteria or evidence.
- Protected evaluation evidence. Explain why the producing process must not freely change the measures used to judge its own work.
- Bounded failure recovery cycle. Trace how Self-Heal Loop handles a failed task: diagnose, repair, verify, then accept or roll back an attempt, continuing only within a budget or handing off.
- Protected recovery boundaries. Explain when Self-Heal Loop has a trustworthy recovery claim and what must be kept outside the repair path.
- Repairable failure boundary. Distinguish a bounded, diagnosable repair from a failure caused by missing authoritative knowledge. Explain when the agent should request that knowledge or hand off the task instead of repeating the loop.
- Modification authority and duties. Explain what modification authority means for a Self-Heal Loop and describe the responsibilities that accompany it. Identify the kinds of state a conservative policy permits the loop to change.
- Protected acceptance evidence. Explain why the verifier, acceptance criteria, and protected tests remain outside the repair loop’s write authority. Describe how the Honk example separates an editable candidate from independent verification.
- Evidence-led recovery sequence. Trace how a recovery attempt moves from capturing a failure and restorable baseline, through diagnosing a cause and proposing a repair, to deciding whether to succeed, continue within budget, roll back, or hand off.
- Authorized reversible repair. Explain how the loop constrains a proposed repair before applying it and preserves the ability to reverse that attempt.
- Protected cost-ordered verification. Describe how protected checks establish recovery and why applicable checks run from cheaper to more expensive, even if a model Critic reviews the proposal.
- System-owned recovery policy. Explain why the surrounding system, rather than the repair-proposing agent, owns the recovery policy and how the trusted workspace checks a proposed change against it.
- Recovery baselines and rollback. Describe when the loop captures a recovery baseline and how it uses checkpoints to undo an unsuccessful repair attempt.
- Missing repair prerequisites. Explain why a Self-Heal Loop must stop when it can detect failure but lacks a way to determine success or the facts needed for repair.
- Protected verification criteria. Describe verifier subversion and how to keep a repair from passing by weakening its test.
- Repair progress and rollback. Explain how repeated repairs can create new failures or leave no restorable baseline, and describe the safeguards given for each problem.
- Cross-run recovery quality. Explain why passing the immediate check does not prove that retained repairs improve the system, and describe the cross-run response and measurements proposed here.
- Reusable Skills and Routing. Explain how Skill Package turns a successful, repeatable way of working into a versioned capability for later tasks, and how Reflection and Route have different roles.
- Evidence Before Skill Traffic. Justify why a candidate Skill needs evidence beyond working alone before it receives traffic, and name the kinds of evidence and outcomes the section calls for.
- Candidate applicability contract. Describe what turns an extracted Skill into a trackable candidate: an applicability contract defining its intended use and requirements, plus a stable identity and a version that changes with its content or dependencies.
- Staged Skill admission gates. Trace how the isolated, coexistence, and trial gates test a candidate before broader activation, including what happens after a failed trial.
- Skill admission and coexistence. Explain why a simple task family may use one active Skill while a complex one may retain several, and how horizontal evaluation decides among candidates.
- Layered Skill routing. Trace how a production router excludes ineligible Skills, narrows the remaining set with evidence, and uses model judgment only for a semantic choice within a small legal set. Describe what happens when one or no active Skill survives.
- Evidence backed Skill admission. Explain what results admission requires, why the Skill-writing model does not verify its own work, and why a passing gate still needs a durable evidence identifier.
- Filtered and evidence based routing. Trace how hard filters and the layered router limit Skill selection, including what happens when evidence cannot support a choice.
- Evidence Driven Skill Proposals. Explain how collected trajectories can lead to proposed Skills or revisions without allowing a reflection job to promote its own output.
- Attributable Operating Records. Describe what an operating record must preserve and why those details matter when investigating a failure.
- Portfolio Review Decisions. Explain how review frequency and Skill maintenance decisions should reflect operating evidence rather than usage alone.
- Reversible Governed Withdrawal. Describe when automated Skill withdrawal is permissible and how the registry keeps it safe and reversible.
- Evidence before Skill activation. Explain why one successful trace should leave a Skill as a candidate, and describe the evidence needed before activation, including tests alongside the active library.
- Skill admission authority limits. Distinguish eligibility to route to an admitted Skill from permission to execute its effects, and contrast that with Experience Replay advice.
- Experience Replay hierarchy. Explain how Experience Replay uses past execution trajectories to guide later work while separating complete traces from more abstract, scoped advice.
- Lesson admission and recall. Describe the separate decisions to record experience, admit a lesson for replay, and recall it for a current task, including the limits on live-context advice.
- Trace-to-lesson admission levels. Trace how a raw execution trace becomes a candidate lesson and then a replayable heuristic, distinguishing compression from the evidence decision.
- Replay advice versus executable skill. Distinguish the advice admitted by Experience Replay from the executable procedure admitted by Skill Package, including the authority limit on replay records.
- Feedback timing and lesson admission. Distinguish immediate from delayed feedback and explain how each affects admitting a lesson: attach an immediate verifier result to the trace within its tested scope, but keep a delayed-outcome trace pending until the real outcome arrives.
- Attribution under delayed outcomes. Explain why a later result may be hard to attribute to the agent’s recommendation, and describe how the replay record and lesson status should reflect that uncertainty.
- Selective replay lifecycle. Trace the record, distill, validate, admit, recall, and observe lifecycle, and explain why fewer lessons are admitted than recorded and fewer still are recalled at runtime.
- Risk based recall triggers. Distinguish preflight recall from targeted recovery recall and describe when this policy uses each, including why ordinary tasks skip recall by default.
- Eligibility before semantic retrieval. Explain why hard filters precede semantic matching, what makes a lesson eligible, and what the system records after recall.
- Distinct experience record states. Describe how the data model separates raw evidence, candidate lessons, and replayable lessons, and why it retains versions and conflicts rather than assigning an early global effectiveness score.
- Evidence-backed lesson admission. Explain the requirements stated here for admitting a lesson to replayable status: a domain-policy repeated-case rule or a causal path with a recorded mechanism, linked external evidence, and task-family scope, while retaining a source trace.
- Triggered scoped lesson recall. Describe how trigger policy avoids unsolicited history on routine tasks while permitting preventive and recovery recall, and how retrieval selects only task-relevant lessons with replay authority and valid scope.
- Outcome-linked recall evidence. Explain why a later outcome must be joined to the recall log and why retrieval, use, decision effect, and outcome remain separate fields.
- Lesson admission and attribution. Explain why a newly distilled lesson must not enter a live prompt before validation, and why an apparent cause in a trace needs stronger evidence before becoming a cross-task lesson.
- Bounded lesson recall. Describe how to prevent Experience Replay from flooding an agent's context with plausible lessons.
- Advisory experience authority boundary. Distinguish using recalled experience for planning and diagnosis from allowing it to authorize actions or policy changes.
- Current and Cross-Task Reflection. Distinguish what each reflection pattern may change during a task or across tasks, and explain how a task trace can lead to separately admitted future capabilities or advice.
- Protected Evaluation and Change Authority. Explain why a reflection loop cannot freely edit the evidence used to judge it, and distinguish changes that may move automatically from those requiring separate human approval.
- Four Composition Design Questions. Describe the four questions used to bound a composed reflection system, and apply them to the example where local safeguards accumulated costs across runs.
- Delivery acceptance conditions. Explain when the coordinator accepts delivery and when it hands the task off after review, verification, or recovery.
- Review status after repair. Explain why recovery that changes an artifact causes handoff, while execution or state-only recovery can still complete.
- Scope matched evaluation signals. Explain why the evaluation evidence stack is not a ranking and how to choose signals for a change: start with the cheapest signal that can decide the question, then broaden evaluation if a failure could escape that signal's scope.
- Protected evaluation set construction. Explain how production traces become evaluation cases rather than automatic benchmark entries, and why the set must be protected and traceable.
- Hard gates in release decisions. Distinguish hard release gates from aggregate scores and state what happens when a gate fails or there is no evidence.
- Current-task feedback paths. Distinguish how Generator-Critic and Self-Heal Loop provide feedback within Argus’s current task.
- Admission of reusable learning. Explain how Argus turns repeatable procedures and traces or outcomes into candidates for future use.
- Controlled routing and recall. Describe when Argus selects active Skills or recalls replayable lessons, and what it records about those decisions.
What it builds on
- The complete pattern map (chapter 2) · The two-dimensional pattern map supplies the Reflection × Chain coordinates.
Section by section
Introduction
The chapter introduction shows why useful fixes to individual agent failures need evaluation across runs to determine whether the system is improving.
- Local fixes and system improvement: Explain why a reflection pass that fixes the current failure cannot, by itself, show that an agent is improving overall. Describe how the accumulated safeguards in the example made builds more stable but also slower and burdened by overlapping or conflicting rules.
Why it matters: A fix that helps today can become part of a costly pattern that only becomes visible across runs.
Key terms: reflection, local checks, repairs, combined cost
7.1 What is reflection?
This section defines reflection as feedback that can change an agent’s behavior and introduces the questions that make such changes trustworthy.
- Reflection design questions: Explain reflection as feedback permitted to change something, and state the three production-design questions: what the feedback can see, when the result will be known, and what the agent may change.
Why it matters: These questions define what feedback can responsibly do in an agent. - Change duration versus result delay: Distinguish changes made before the current task ends from changes carried into later work, and distinguish that duration from the delay before a result is known.
Why it matters: A change’s persistence does not tell you how soon you can judge its result. - Evidence matched to claims: Justify why evidence for a reflection-driven change must match the claim being made, using the contrast between a unit test and the long-term cost of many patches.
Why it matters: Matching evidence to the claim prevents a narrow success from being mistaken for a broader improvement.
Key terms: reflection, feedback, current task, later work, evidence, unit test
7.1.1 Why another pass is not enough
Explains why a second pass is not reliable reflection by itself and how grounded evidence and a distinct review perspective make critique more dependable.
- Limits of unguided reconsideration: Explain why asking an LLM to reconsider an answer without new evidence is not a reliable error check.
Why it matters: It keeps a polished revision from being mistaken for a verified correction. - Evidence-grounded verification: Describe why reflection is more dependable when the reviewer can check an artifact against evidence, and give a section example of such a check.
Why it matters: A check tied to evidence gives a reviewer a stronger basis than critique alone. - Independent review perspective: Distinguish a genuinely useful Critic from merely adding another model or model family.
Why it matters: Review is stronger when it challenges the Generator's basis rather than repeating it.
Key terms: intrinsic self-correction, second pass, probabilistic generation, verification, focused regression test, tool-interactive feedback, evidence, Critic, Generator, review frame
7.2 Pattern: Generator-Critic
Introduces Generator-Critic as a separate review path for a current artifact, with explicit review criteria and bounded iteration.
- Separate production and review: Explain how a Generator creates an artifact, a Critic reviews it against stated criteria and available evidence, and the Generator revises that same artifact or delivers it when review is satisfied.
Why it matters: A separate review path gives the agent a chance to check its work before delivery. - Critic evidence and review contract: Describe what must be specified for a useful review: the artifact version, the Critic's criteria and evidence, permitted verdicts, and a stop policy. Explain why giving the Critic the Generator's same assumptions and evidence can preserve a blind spot.
Why it matters: Another review is not necessarily an independent check if it inherits the original blind spot. - Bounded chain and review cost: Explain that Generator-Critic is Reflection × Chain: one generate–critique–revise traversal may suffice, while a return to the Critic should be bounded and worthwhile. State the suggested measures for judging that tradeoff.
Why it matters: Bounded review helps avoid paying for repeated checks that do not improve the artifact.
Key terms: Generator, Critic, artifact, generate -> critique -> revise, criteria, evidence, permitted verdicts, stop policy, blind spot, Reflection × Chain
7.2.1 One artifact, a different line of inquiry
This section explains why Generator-Critic review must examine an artifact through a different line of inquiry, make claims only within its evidence, and return critique to improve that artifact.
- A Different Review Inquiry: Explain why a Critic must do more than repeat the Generator's reasoning, using the SQL example to show how a different question or evidence can expose a shared assumption.
Why it matters: A second pass may repeat the original mistake unless it can test a different assumption. - Evidence-Bounded Feedback Scope: Describe feedback scope and distinguish what syntax checks, execution, expected-row tests, and domain review can establish. Explain why a human reviewer also needs a focused question and relevant evidence.
Why it matters: Defined scope keeps a review from claiming more than its evidence supports and gives a human reviewer a tractable task. - Reflection Versus Adversarial Review: Distinguish Generator-Critic reflection on one artifact from Adversarial Review of a contested claim.
Why it matters: The distinction clarifies whether review is improving an artifact or resolving a dispute.
Key terms: Generator, Critic, line of inquiry, cross-model review, feedback scope, domain reviewer, review scope, Generator-Critic, reflection pattern, Adversarial Review
7.2.2 Design the Critic before adding iterations
This section establishes the Critic contract as the priority, then explains how to bound review iterations and measure whether critique improves results.
- Critic contract priority: Explain why defining a useful Critic contract matters more than choosing whether the Critic is a model, tool, or person.
Why it matters: A clear review contract keeps attention on what the Critic must do, not just who or what performs the review. - Bounded critique iterations: Describe what to record during critique and revision, when to stop iterating, and why to preserve the best artifact seen so far.
Why it matters: Bounded, recorded iterations make it possible to improve an artifact without spending indefinitely or losing an earlier improvement. - Calibrated critique measurements: State which measurements can show whether critique helps, and explain why thresholds should be calibrated on the team's own tasks and outcomes.
Why it matters: A locally calibrated measure helps the team judge whether review improves its work enough to justify its time and cost.
Key terms: Critic contract, Critic, iteration, review budget, best known artifact, confirmed-issue precision, task quality, iterations to acceptance, oscillation rate, latency
7.2.3 Building Generator-Critic
This section outlines a Generator-Critic implementation that keeps critiques traceable to independent evidence and artifact versions, then selects the best version using domain evidence.
- Traceable independent review evidence: Explain how review findings remain traceable and how evidence is collected separately from the Critic.
Why it matters: A critique is more useful when its findings can be checked against identifiable evidence. - Critique and artifact pairing: Describe what a single review traversal returns and why the artifact version matters.
Why it matters: Pairing the critique with its inspected version keeps the feedback tied to the artifact it addresses. - Evidence based best version: Explain how the bounded implementation handles iterations and chooses which artifact version to preserve.
Why it matters: Iteration should retain a version that performs well by relevant evidence, not merely one another model likes.
Key terms: review objects, evidence identifiers, verdict, Critic, review traversal, Critique, artifact version, bounded implementation, best-version preservation, select_best
7.2.4 When Generator-Critic breaks
This section identifies ways Generator-Critic review can fail and the safeguards that keep critique, revision, and evaluation trustworthy.
- Independent evidence-grounded critique: Explain why a Critic needs a different review path from the Generator and why its findings must be tied to criteria or evidence.
Why it matters: A second pass is useful only if it can catch missed assumptions without damaging correct work through invented issues. - Calibrated criterion-level acceptance: Describe rubber-stamp acceptance and how to make a Critic's favorable judgment more meaningful.
Why it matters: An approving score is not reliable evidence that the artifact actually meets the criteria. - Oscillation and best-version recovery: Explain how revisions can oscillate and what to do when the same problems recur.
Why it matters: Recognizing a revision cycle prevents repeated edits from replacing the best available artifact. - Protected evaluation evidence: Explain why the producing process must not freely change the measures used to judge its own work.
Why it matters: Review loses its value if the artifact's producer can quietly change what counts as passing.
Key terms: Shared blind spot, Critique hallucination, Critic, Generator, Rubber-stamp acceptance, criterion-level findings, self-preference, position effects, Oscillation, issue and artifact signatures
7.3 Pattern: Self-Heal Loop
Introduces Self-Heal Loop as bounded, verifiable recovery from a failed task, with explicit limits on what repair may change.
- Bounded failure recovery cycle: Trace how Self-Heal Loop handles a failed task: diagnose, repair, verify, then accept or roll back an attempt, continuing only within a budget or handing off.
Why it matters: A recovery loop is useful only if it can tell whether a repair worked and has a bounded way to proceed when it did not. - Protected recovery boundaries: Explain when Self-Heal Loop has a trustworthy recovery claim and what must be kept outside the repair path.
Why it matters: Protected checks and a restorable starting point make a repair result credible rather than merely self-approved.
Key terms: Self-Heal Loop, Reflection × Loop, rollback, handoff, recovery envelope, writable and protected state, baseline, verifier
7.3.1 Recovery requires permission and responsibility
This section defines what a Self-Heal Loop may repair, what it must verify, and when it must hand off or seek separate approval.
- Repairable failure boundary: Distinguish a bounded, diagnosable repair from a failure caused by missing authoritative knowledge. Explain when the agent should request that knowledge or hand off the task instead of repeating the loop.
Why it matters: It keeps an agent from treating every failure as something another retry can solve. - Modification authority and duties: Explain what modification authority means for a Self-Heal Loop and describe the responsibilities that accompany it. Identify the kinds of state a conservative policy permits the loop to change.
Why it matters: An explicit recovery envelope makes repairs controllable and recoverable. - Protected acceptance evidence: Explain why the verifier, acceptance criteria, and protected tests remain outside the repair loop’s write authority. Describe how the Honk example separates an editable candidate from independent verification.
Why it matters: A repair is credible only if the agent cannot make it pass by weakening its own checks. - Persistent change approval: Distinguish proposing a persistent change from merging or retiring it. Describe when a separate cross-run process may handle a low-risk change and when human approval remains necessary.
Why it matters: A successful local repair should not silently become a lasting rule for other tasks.
Key terms: Self-Heal Loop, authoritative domain knowledge, handoff, modification authority, rollback point, recovery envelope, verifier, acceptance criteria, protected tests, independent verifiers
7.3.2 The fail-diagnose-fix-verify loop
This section lays out a bounded recovery loop that uses failure evidence to propose repairs, applies only authorized changes, and verifies recovery efficiently.
- Evidence-led recovery sequence: Trace how a recovery attempt moves from capturing a failure and restorable baseline, through diagnosing a cause and proposing a repair, to deciding whether to succeed, continue within budget, roll back, or hand off.
Why it matters: A defined sequence keeps recovery grounded in evidence and gives each attempt a clear stopping decision. - Authorized reversible repair: Explain how the loop constrains a proposed repair before applying it and preserves the ability to reverse that attempt.
Why it matters: A recovery attempt should not gain authority over protected state or leave changes that cannot be safely undone. - Protected cost-ordered verification: Describe how protected checks establish recovery and why applicable checks run from cheaper to more expensive, even if a model Critic reviews the proposal.
Why it matters: Verification catches both an unfixed failure and new breakage without paying for expensive checks after an early failure.
Key terms: Capture, Diagnose, Propose, Decide, restorable baseline, declared writable scope, Check authority, Apply atomically, checkpoint, sandbox
7.3.3 Building Self-Heal Loop
This section shows how to build a Self-Heal Loop that keeps repair proposals within system-defined authority, restores failed attempts, detects lack of progress, and records a useful handoff.
- System-owned recovery policy: Explain why the surrounding system, rather than the repair-proposing agent, owns the recovery policy and how the trusted workspace checks a proposed change against it.
Why it matters: A proposed fix must not be able to grant itself permission to change more than the system allows. - Recovery baselines and rollback: Describe when the loop captures a recovery baseline and how it uses checkpoints to undo an unsuccessful repair attempt.
Why it matters: A failed fix should leave the workspace in a recoverable state rather than compound the original failure. - Domain-specific progress checks: Explain why the bounded loop needs a domain-supplied no-progress check rather than one universal comparison.
Why it matters: The loop needs a task-appropriate way to recognize when further repair attempts are not helping. - Recoverable investigation handoff: Describe what the handoff record should preserve and why a failed branch or snapshot must remain separate from production state.
Why it matters: A clear record lets a person pick up a failed recovery without repeating the investigation or deploying failed state.
Key terms: recovery policy, structured change, trusted workspace, authority check, allowed tool set, baseline, checkpoint, atomic application, verification, regression
7.3.4 When Self-Heal Loop breaks
This section identifies ways a Self-Heal Loop can fail and explains why safe recovery requires trustworthy verification, rollback, and measurement beyond the current task.
- Missing repair prerequisites: Explain why a Self-Heal Loop must stop when it can detect failure but lacks a way to determine success or the facts needed for repair.
Why it matters: Without a way to check success or obtain needed facts, more repair attempts cannot establish that the problem is fixed. - Protected verification criteria: Describe verifier subversion and how to keep a repair from passing by weakening its test.
Why it matters: Protecting the success criterion prevents the agent from mistaking an easier test for a real repair. - Repair progress and rollback: Explain how repeated repairs can create new failures or leave no restorable baseline, and describe the safeguards given for each problem.
Why it matters: A repair loop is safer when it can detect worsening results and restore the state it started from. - Cross-run recovery quality: Explain why passing the immediate check does not prove that retained repairs improve the system, and describe the cross-run response and measurements proposed here.
Why it matters: A series of green tests can conceal a system that becomes slower, costlier, or harder to maintain across tasks.
Key terms: missing oracle or knowledge, verifier, domain knowledge, verifier subversion, tests, acceptance criteria, whack-a-mole repair, failure signatures, regression results, rollback gap
7.4 Pattern: Skill Package
This section introduces Skill Package as a way to reuse successful procedures on later tasks, while distinguishing the package itself from the decisions that admit and route it.
- Reusable Skills and Routing: Explain how Skill Package turns a successful, repeatable way of working into a versioned capability for later tasks, and how Reflection and Route have different roles.
Why it matters: A reusable procedure helps only if the agent can select it for an appropriate later task. - Skill Package and Discovery: Describe what a Skill package contains and why its discovery information matters for tasks expressed in natural language.
Why it matters: Packaging makes a capability available; discovery information helps the runtime find it without making it automatically safe to deploy. - Evidence Before Skill Traffic: Justify why a candidate Skill needs evidence beyond working alone before it receives traffic, and name the kinds of evidence and outcomes the section calls for.
Why it matters: Evidence before rollout helps prevent a promising Skill from making the wider agent worse.
Key terms: Skill Package, Reflection × Route, general solver, Skill, discovery metadata, SKILL.md, interface, dependencies, version, applicability contract
7.4.1 A successful run creates a candidate
A successful run can propose a reusable Skill, but an applicability contract and staged admission tests are needed before it joins the active library.
- Limits of successful traces: Explain why a successful execution trace, or even an isolated benchmark, does not establish that a Skill is ready for use in an existing library.
Why it matters: This distinction prevents one good run from being mistaken for evidence that a Skill is safe to activate. - Candidate applicability contract: Describe what turns an extracted Skill into a trackable candidate: an applicability contract defining its intended use and requirements, plus a stable identity and a version that changes with its content or dependencies.
Why it matters: A defined, versioned candidate can be tested and revised without confusing it with an already approved capability. - Staged Skill admission gates: Trace how the isolated, coexistence, and trial gates test a candidate before broader activation, including what happens after a failed trial.
Why it matters: Separate gates catch failures that a standalone success cannot reveal while limiting the exposure of an unproven Skill.
Key terms: successful trace, isolated benchmark, coexist, router, candidate, applicability contract, stable logical identity, version, isolated gate, coexistence gate
7.4.2 One active Skill or conditional coexistence
This section explains when to keep one active Skill, merge duplicates, or retain multiple Skills for different conditions.
- Skill admission and coexistence: Explain why a simple task family may use one active Skill while a complex one may retain several, and how horizontal evaluation decides among candidates.
Why it matters: The agent needs useful alternatives without accumulating redundant Skills that complicate routing and evaluation.
Key terms: Skill, admission process, applicability contract, horizontal evaluation
7.4.3 Route in layers
Skill routing should use eligibility rules and task evidence before model judgment, rather than choosing a routing method by library size alone.
- Layered Skill routing: Trace how a production router excludes ineligible Skills, narrows the remaining set with evidence, and uses model judgment only for a semantic choice within a small legal set. Describe what happens when one or no active Skill survives.
Why it matters: This keeps the router from selecting an unsuitable Skill just because one appears to match. - Library size as routing criterion: Explain why library size alone cannot determine whether routing should use model judgment or vector search.
Why it matters: A simple small-versus-large rule can overlook the conditions that make a routing choice safe and clear.
Key terms: Rules exclude, Evidence narrows, model interprets context, general solver, library size, model judgment, vector search, plausible matches
7.4.4 Building Skill Package
This section sketches how Skill Packages are represented, admitted with independent evidence, and routed through eligibility checks before selection.
- Skill identity and evidence records: Describe how the data model separates a stable capability identity from its current version and keeps evidence beside its state.
Why it matters: This makes it possible to discuss a capability separately from a particular version and its evidence. - Evidence backed Skill admission: Explain what results admission requires, why the Skill-writing model does not verify its own work, and why a passing gate still needs a durable evidence identifier.
Why it matters: A Skill is not admitted solely because its author or a passing gate says it is ready. - Filtered and evidence based routing: Trace how hard filters and the layered router limit Skill selection, including what happens when evidence cannot support a choice.
Why it matters: Routing must not select an ineligible Skill or force a choice unsupported by evidence.
Key terms: stable capability identity, current version, evidence, state, admission function, independent, isolated, coexistence, trial results, durable evidence identifier
7.4.5 Maintain the library from operating evidence
This section explains how to maintain a Skill library using operating evidence while keeping promotion and withdrawal subject to safeguards.
- Evidence Driven Skill Proposals: Explain how collected trajectories can lead to proposed Skills or revisions without allowing a reflection job to promote its own output.
Why it matters: Separating proposal from admission lets the library learn from use without treating an automated suggestion as an approved Skill. - Attributable Operating Records: Describe what an operating record must preserve and why those details matter when investigating a failure.
Why it matters: Without enough context around a run, maintainers may change the wrong part of the system. - Portfolio Review Decisions: Explain how review frequency and Skill maintenance decisions should reflect operating evidence rather than usage alone.
Why it matters: A rarely used but critical Skill should not disappear merely because a usage metric is low. - Reversible Governed Withdrawal: Describe when automated Skill withdrawal is permissible and how the registry keeps it safe and reversible.
Why it matters: Withdrawal can reduce a library’s problems without losing the ability to recover a needed Skill or bypassing protected decisions.
Key terms: trajectories, reflection job, admission path, operating record, hard filtering, selected version, Harness versions, processing cadence, portfolio review, weighted scores
7.4.6 When Skill Package breaks
This section identifies ways Skill Packages can fail and the evidence, maintenance, and authority boundaries that keep them reliable.
- Evidence before Skill activation: Explain why one successful trace should leave a Skill as a candidate, and describe the evidence needed before activation, including tests alongside the active library.
Why it matters: A promising Skill can make the overall system worse even when it succeeds on its own. - Ambiguous Skill routing: Describe how loosely described, overlapping Skills cause inconsistent selection and how to narrow or decline a match.
Why it matters: Clear applicability makes Skill selection more dependable when the library contains overlapping choices. - Skill library upkeep: Explain how obsolete dependencies and portfolio sprawl undermine Skills, and describe the evidence-based responses.
Why it matters: A Skill library needs ongoing evidence-based maintenance, not just an initial admission decision. - Skill admission authority limits: Distinguish eligibility to route to an admitted Skill from permission to execute its effects, and contrast that with Experience Replay advice.
Why it matters: Being allowed to select a Skill is not the same as authorizing everything it might do.
Key terms: candidate, isolated, coexistence, trial evidence, active library, routing ambiguity, applicability contracts, hard filters, evidence narrowing, abstention
7.5 Pattern: Experience Replay
This section introduces Experience Replay as a way to turn past execution into relevant, evidence-backed advice for later tasks without putting unverified lessons into live context.
- Different feedback clocks: Distinguish the feedback available to coding and operations agents, and explain why recording a trace is different from establishing a lesson.
Why it matters: The delay between a run and its outcome affects when its experience is safe to reuse. - Experience Replay hierarchy: Explain how Experience Replay uses past execution trajectories to guide later work while separating complete traces from more abstract, scoped advice.
Why it matters: The hierarchy lets an agent benefit from prior work without treating an entire raw trace as current advice. - Lesson admission and recall: Describe the separate decisions to record experience, admit a lesson for replay, and recall it for a current task, including the limits on live-context advice.
Why it matters: These boundaries keep an unverified or irrelevant past lesson from steering a new task.
Key terms: feedback clocks, execution traces, immediate label, Experience Replay, execution trajectories, Reflection × Hierarchy, scoped heuristics, raw traces, candidate lessons, replayable heuristics
7.5.1 From an execution trace to a replayable lesson
This section explains how execution traces become evidence-backed, context-specific lessons without becoming executable instructions.
- Trace-to-lesson admission levels: Trace how a raw execution trace becomes a candidate lesson and then a replayable heuristic, distinguishing compression from the evidence decision.
Why it matters: A stored observation should not become reusable advice merely because it has been summarized. - Conditions for conflicting lessons: Explain why conflicting experiences should retain their observed conditions rather than be reduced to one global winner.
Why it matters: Preserving context prevents advice from one environment from being applied as a universal rule. - Replay advice versus executable skill: Distinguish the advice admitted by Experience Replay from the executable procedure admitted by Skill Package, including the authority limit on replay records.
Why it matters: A useful past lesson must not silently grant the agent new authority.
Key terms: L0, raw trace, L1, candidate lesson, L2, replayable heuristic, conflicting experiences, applicability, conditions, Experience Replay
7.5.2 Feedback latency changes the admission test
The section explains how the timing and reliability of outcome evidence determine when an execution trace can support a replayable lesson.
- Feedback timing and lesson admission: Distinguish immediate from delayed feedback and explain how each affects admitting a lesson: attach an immediate verifier result to the trace within its tested scope, but keep a delayed-outcome trace pending until the real outcome arrives.
Why it matters: It prevents an agent from treating an early signal—or a test with limited coverage—as proof of a broader success. - Attribution under delayed outcomes: Explain why a later result may be hard to attribute to the agent’s recommendation, and describe how the replay record and lesson status should reflect that uncertainty.
Why it matters: Preserving what happened between recommendation and outcome keeps later learning from claiming more certainty than the evidence supports.
Key terms: feedback latency, verifier result, trace, proxy, lesson, attribution, replay record, causal link, hypothesis, domain expert
7.5.3 Record, admit, and recall
This section explains how experience replay moves from recorded lessons to selective recall, with eligibility checks and outcome tracking.
- Selective replay lifecycle: Trace the record, distill, validate, admit, recall, and observe lifecycle, and explain why fewer lessons are admitted than recorded and fewer still are recalled at runtime.
Why it matters: A lesson should earn its place in the agent’s limited runtime context. - Risk based recall triggers: Distinguish preflight recall from targeted recovery recall and describe when this policy uses each, including why ordinary tasks skip recall by default.
Why it matters: Triggering recall selectively reserves context for lessons likely to help the current task. - Eligibility before semantic retrieval: Explain why hard filters precede semantic matching, what makes a lesson eligible, and what the system records after recall.
Why it matters: A semantically similar lesson should not influence a decision unless it is eligible for this task and environment.
Key terms: record, distill, validate, admit, recall, observe, preflight recall, targeted recovery recall, item budget, context cost
7.5.4 Building Experience Replay
This section shows how to represent, admit, recall, and evaluate lessons in Experience Replay without treating a successful outcome as proof of causation.
- Distinct experience record states: Describe how the data model separates raw evidence, candidate lessons, and replayable lessons, and why it retains versions and conflicts rather than assigning an early global effectiveness score.
Why it matters: Keeping these states separate prevents a tentative lesson from being treated as established guidance. - Evidence-backed lesson admission: Explain the requirements stated here for admitting a lesson to replayable status: a domain-policy repeated-case rule or a causal path with a recorded mechanism, linked external evidence, and task-family scope, while retaining a source trace.
Why it matters: An admitted lesson needs a basis that can be inspected and a scope in which it applies. - Triggered scoped lesson recall: Describe how trigger policy avoids unsolicited history on routine tasks while permitting preventive and recovery recall, and how retrieval selects only task-relevant lessons with replay authority and valid scope.
Why it matters: Selective recall avoids burdening routine tasks with irrelevant or unauthorized history. - Outcome-linked recall evidence: Explain why a later outcome must be joined to the recall log and why retrieval, use, decision effect, and outcome remain separate fields.
Why it matters: Outcome tracking can improve the evidence for a lesson without overstating what caused a task to succeed.
Key terms: raw evidence, candidate lessons, replayable lessons, versions, conflicts, admission, repeated-case rule, domain policy, causal path, task-family scope
7.5.5 When Experience Replay breaks
This section identifies five ways Experience Replay can fail and the boundaries that keep recalled lessons useful and safe.
- Lesson admission and attribution: Explain why a newly distilled lesson must not enter a live prompt before validation, and why an apparent cause in a trace needs stronger evidence before becoming a cross-task lesson.
Why it matters: Without an admission boundary, an unvalidated or misattributed lesson can influence later work. - Bounded lesson recall: Describe how to prevent Experience Replay from flooding an agent's context with plausible lessons.
Why it matters: Selective recall keeps the agent from having to sort through every plausible past lesson. - Lesson validity over time: Explain how a lesson can become stale or conflict with other advice, and describe the safeguards the section gives.
Why it matters: Even a sound lesson may need rechecking when the conditions behind it change. - Advisory experience authority boundary: Distinguish using recalled experience for planning and diagnosis from allowing it to authorize actions or policy changes.
Why it matters: A useful remembered lesson must not become a shortcut around controls on consequential actions.
Key terms: candidate leakage, replayable stores, superstitious learning, cross-task admission, context flooding, recall, hard scope filters, context budget, stale or conflicting advice, version constraints
7.6 Composing reflection patterns
This section shows how four reflection patterns can share evidence while keeping current-task changes, cross-task learning, and authority to change safeguards separate.
- Current and Cross-Task Reflection: Distinguish what each reflection pattern may change during a task or across tasks, and explain how a task trace can lead to separately admitted future capabilities or advice.
Why it matters: Separating immediate correction from retained learning keeps reflection from becoming one unbounded loop. - Protected Evaluation and Change Authority: Explain why a reflection loop cannot freely edit the evidence used to judge it, and distinguish changes that may move automatically from those requiring separate human approval.
Why it matters: Independent evidence prevents an agent from declaring success by weakening its own checks. - Four Composition Design Questions: Describe the four questions used to bound a composed reflection system, and apply them to the example where local safeguards accumulated costs across runs.
Why it matters: These questions expose effects and permissions that a successful local check alone cannot settle.
Key terms: Generator-Critic, Self-Heal Loop, Skill Package, Experience Replay, trace, admission path, protected evidence, writable path, regression-tested changes, human approval
7.6.1 A current-task coordinator
This section explains how a current-task coordinator decides whether to deliver or hand off an artifact after review and verification, while recording a trace for possible cross-run learning.
- Delivery acceptance conditions: Explain when the coordinator accepts delivery and when it hands the task off after review, verification, or recovery.
Why it matters: These conditions prevent a failed or unresolved check from being mistaken for a deliverable result. - Review status after repair: Explain why recovery that changes an artifact causes handoff, while execution or state-only recovery can still complete.
Why it matters: A repair can invalidate the earlier review even if it fixes the immediate failure. - Trace recording and admission boundary: Describe what the coordinator records and what it does not authorize for cross-run learning.
Why it matters: Recording evidence for later learning is different from approving that learning for reuse.
Key terms: accepted review, initial verification, recovered healing, handed off, review status, reviewed artifact, protected verifier, execution or state-only recovery, trace, Skill
7.7 Evaluation belongs beside the change
This section explains how to choose evaluation evidence that fits the question and the ways each reflection pattern can fail.
- Scope matched evaluation signals: Explain why the evaluation evidence stack is not a ranking and how to choose signals for a change: start with the cheapest signal that can decide the question, then broaden evaluation if a failure could escape that signal's scope.
Why it matters: This helps you avoid both unnecessary evaluation cost and false confidence from a narrow check. - Pattern specific evaluation evidence: Describe how the reflection patterns call for different evaluation evidence, using examples from the section rather than treating one check as sufficient for every pattern.
Why it matters: Matching evidence to the pattern makes the evaluation relevant to the change being made.
Key terms: evaluation evidence stack, signals, Generator-Critic, Self-Heal, Skill Package, Experience Replay
7.7.1 Build and protect the evaluation set
This section explains how to turn production failures into a trustworthy evaluation set and use protected evidence, hard gates, and cost measures to make release decisions.
- Protected evaluation set construction: Explain how production traces become evaluation cases rather than automatic benchmark entries, and why the set must be protected and traceable.
Why it matters: A curated, protected set makes regressions meaningful instead of letting flawed or leaked cases distort the result. - Hard gates in release decisions: Distinguish hard release gates from aggregate scores and state what happens when a gate fails or there is no evidence.
Why it matters: Keeping gates separate prevents a good average from concealing a release-blocking regression. - Effect and cost measures: Explain why a release view must pair measures of an agent's effects with measures of the cost of achieving them.
Why it matters: Success is not enough if obtaining it makes the agent too slow or expensive to operate.
Key terms: production traces, evaluation set, protected evidence, provenance, regression set, hard gates, aggregate scores, composite scores, promotion, invariant
7.8 Argus checkpoint: Reflection
This checkpoint summarizes how Argus uses reflection for feedback within a task, admits selected learning for later use, and records its reuse decisions.
- Current-task feedback paths: Distinguish how Generator-Critic and Self-Heal Loop provide feedback within Argus’s current task.
Why it matters: The two patterns respond to different kinds of problems in the current task. - Admission of reusable learning: Explain how Argus turns repeatable procedures and traces or outcomes into candidates for future use.
Why it matters: Learning from a run is a candidate for reuse, not automatically an active capability or replayable lesson. - Controlled routing and recall: Describe when Argus selects active Skills or recalls replayable lessons, and what it records about those decisions.
Why it matters: Restricted choices and recorded outcomes make Argus’s reuse decisions inspectable.
Key terms: Generator-Critic, Self-Heal Loop, protected verifier, Skill candidate, capability admission, Experience candidate, replay admission, active Skills, replayable lessons, legal candidate set
7.9 Summary
7.10 References
This section lists sources for the chapter’s discussion of reflection and evaluation.
Where this is used later
- Argus as a composition self-test (chapter 10) · Reflection as an audit of the agent's work
- Pattern: Adversarial Review (chapter 8) · Supplies the boundary used to distinguish Adversarial Review from Generator-Critic reflection.
- Enforcing the current trust boundary (chapter 9) · Supports enforcing boundaries on what autonomous changes are permitted.
- Evals make drift visible (chapter 11) · Building and maintaining an evaluation set.
Concepts explained in this chapter
- agent skillA packaged agent capability that specifies how to perform a class of tasks, including relevant tools and workflow guidance.
- generator-critic loopA pattern in which a generator produces a candidate result and a critic evaluates it to guide revision or delivery.
- fail-diagnose-fix-verify loopA process for recovering from a failure by capturing its context, diagnosing a cause, proposing and applying a repair, verifying the result, and deciding what to do next.
- experience replayA pattern that uses past execution trajectories and relevant parts of their history to guide later work.
- evaluationEvaluation is the systematic assessment of a result against criteria for quality, correctness, or suitability.
- reflectionAn agent capability for inspecting and revising its own intermediate results or proposed actions.
- recoveryThe process of restoring a system or its operation after a failure or interruption.
- checkpointingThe practice of recording execution state at checkpoints so a workflow can resume after interruption.
- verifierA verifier is a component that checks whether an answer or result satisfies relevant criteria.
- admissionTool admission is a check that a proposed tool operation remains authorized and appropriate given current authority, provenance, and state freshness.
- verificationThe process of checking whether a system or result satisfies specified requirements or properties.
- tool contractA description of a tool's execution requirements, including checks and information needed by its runner.
- skill libraryA collection of Skills maintained for selection and reuse by an agent system.
- trajectoryA record of events and operations during a system run, arranged to show its progression and support diagnosis.
- validationValidation is the process of assessing whether a candidate lesson is suitable to influence a later task.
- LLM-as-a-judgeModel-based judging is the assessment of outputs using a model as the judge.
- evidenceInformation that supports or substantiates a claim or decision.
These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.
