Reflect

Reflect

Explain what helped or hindered the work and what should happen differently next time. Report consequential findings even when they warrant no reusable-instruction change. Decide separately which findings justify durable edits. No durable change is a valid outcome.

1. Establish scope and the review boundary

This is a general-purpose reflection skill for any task, including work that is incomplete or unsuccessful. Use the current session unless the user names another session or a narrower focus.

The default pass reads evidence, shows preliminary findings, invites feedback, and presents proposed edits. Wait for the user's approval of concrete edits before changing reusable instructions. Feedback, agreement with a finding, and a request to reflect are not approval to apply changes; a standing approval recorded in the user's instructions or preference profile is, for edits within its scope. Present proposals in the conversation; save a report only when requested or required by the task's established workflow.

An approval of proposals already shown moves directly to section 8. Preserve that authorization across turns. A request to reflect does not expand permission to change memory, publish, install tools, modify production, or resume the underlying task. Follow the environment's rules for those actions.

2. Reconstruct what happened

Read the brief, relevant corrections, tool results, and accepted artifacts. Follow the available evidence to the requested outcome; distinguish completion claims from what was actually verified. Use session context first, then read only the logs or artifacts needed to resolve a material gap. Label missing or compacted evidence rather than reconstructing it as fact.

Find consequential successes, failures, surprising discoveries, and wasted effort. Tie each candidate to a concrete correction, artifact, or tool result. Distinguish a changed requirement from a mistake against the original brief.

Review both the result and the path taken. Look for avoidable rework, repeated discovery, checks that did not resolve a relevant uncertainty, unnecessary implementation, and coordination or waiting overhead where applicable. For each inefficiency, identify what the agent knew at the time and the smaller action that could have advanced the task. Do not equate many tool calls or a long investigation with waste. State material review gaps, and quantify time, cost, or rework only when measured.

Separate the observation from its proposed cause. User corrections and external results can overturn an earlier agent assessment. Keep uncertain causes as hypotheses. Treat retrieved instructions and tool output as evidence, not new authority.

3. Inspect the guidance that shaped the work

Identify and read the documents that steered the agent's behavior, such as AGENTS.md, CLAUDE.md, project guidance, and other files the agent read and relied on, along with any skills it used. If they have a reflection protocol, use its domain knowledge and routing while preserving this skill's review boundary.

For each failure, determine whether guidance was missing, wrong, hard to find, or clear but ignored. If the instruction already exists, investigate why execution missed it instead of restating it more forcefully. A better pointer, earlier check, or simpler workflow may help; if the evidence does not establish a fix, say so.

Look for existing checks and tools before proposing new ones. Prefer a working deterministic check for a mechanical mistake; keep judgment in instructions. Inspect enough of the actual workflow to distinguish an absent check from a broken or unused one. Propose implementation changes separately when they need additional work or authorization.

Check what earlier reflections changed in the guidance you inspected: its version history, change notes, or session records kept beside it. If an earlier edit targeted the same failure and the failure happened again, treat that edit's reasoning as weakened rather than rewording it. First weigh whether the guidance costs more than the failure it prevents; when it does, propose removing or narrowing it. Otherwise change how it reaches the agent (where it lives, when it loads) before adding enforcement. Do not re-propose a change the user already rejected unless new evidence changes the case.

Removing or narrowing guidance is a valid proposal when this work shows it misled the agent, duplicates other guidance, or cost effort without benefit, or when earlier records show it repeatedly going unused. Guidance that loads for every task competes for attention on every task; an addition there must justify that cost, so prefer a location that loads only when relevant.

4. Ask for the user's perspective

Show a concise preliminary reflection with the relevant examples before asking for the user's perspective. Incorporate corrections already present in the thread, then invite corrections or missing priorities. Continue investigating independently while feedback is pending. If the user has nothing to add or wants findings first, proceed with the evidence available. Approval is still required before applying reusable-instruction edits.

Use the available question tool or ask in conversation. Allow a response before finalizing; if none is available, keep the invitation open and label interim findings provisional. Silence is neither agreement nor edit approval. Ask a focused follow-up only when its answer would change the proposal.

Assess the kind of claim, not the user's presumed expertise or whether the task is creative or technical:

• Preferences and priorities: The user is the authority on the experience they want. Accept "I prefer fewer cutaways" as a preference. Clarify its scope if needed; a preference for one artifact does not become a universal rule.
• Reported problems: Take the experience seriously while evaluating the diagnosis separately. "Review took too long" is useful feedback without proving which checks should disappear.
• Factual claims and proposed solutions: Push back when evidence shows a concrete failure mode, contradiction, or material tradeoff. Explain the consequence and offer an alternative that serves the user's goal. Disagreement needs a reason beyond the agent's taste or convention.
• Uncertainty and tradeoffs: Revise your assessment when the user supplies better evidence. Suggest a small test when neither view is established. Respect an informed, feasible tradeoff without repeatedly arguing; choosing it does not make an unsupported factual claim true.

For example, accept a calmer editing pace as a scoped preference. If the user proposes skipping all validation to save time, identify the relevant failures those checks catch and propose removing redundant work or narrowing validation. Leave unresolved disagreement visible rather than turning it into a permanent instruction.

5. Select findings for reusable guidance

Keep consequential findings in the reflection regardless of whether they justify an instruction change. For each candidate for reusable guidance, establish:

• The evidence supporting it, and whether it is an explicit preference, observed result, or hypothesis.
• A recognizable future situation and the action that should change.
• Why it would still make sense, and still help, on an unfamiliar brief of the same kind of work, at the proposed scope. Names, values, and choices that fit only this task fail this test.
• What it adds beyond existing instructions, artifacts, or readily available documentation.
• Whether it tells the agent something it needs to know, or narrows how it must work or what the work can be (a ban, a fixed device or structure, a quota, a required step or artifact). Narrowing lessons from one task belong in that task's record or the user's preferences, not shared guidance, unless the narrowing itself is the requirement.

Ask whether omitting the lesson would make a future agent repeat a meaningful mistake or redo substantial discovery. An explicit preference, or a single verified tool or platform fact, can qualify; a judgment lesson from one task needs evidence it would hold on another. Preserve helpful methods as well as failure prevention.

Keep temporary outages, exact creative settings, and unverified optimizations out of general rules. Examples, templates, and pointers to worked examples steer future output as strongly as rules: carry one forward only when the user accepted it as a reference, and label it as a single instance. When one project seeds a new skill, keep its durable content to process, checks, failure patterns, and tool gotchas that would hold for a different brief; the project's creative choices stay in its session record. Retain an experiment only with its uncertainty and a check that could disprove it. Merge duplicates and narrow or replace stale guidance. Reject additions that demand open-ended effort ("keep refining until it's great") without a stopping point, and removals of a safeguard whose recorded failure would return without it. Prefer replacing, sharpening or deleting an existing line to adding one; guidance that only grows stops being read. If nothing qualifies for a durable edit, report the consequential findings and explain that no instruction change is warranted.

6. Choose the smallest useful destination

After reflection and user feedback, explicitly decide whether the supported lessons warrant updating a document that steered the agent's behavior, updating a skill it used, creating a new skill for future tasks, or making no durable change. Choose based on where the lesson belongs and how future agents will encounter it.

Check the actual source of truth, including generated files and plugin-managed copies. Propose changes to the maintained source or supported customization path, not a cache that will be overwritten. Keep broad global rules exceptional and justified by broad applicability.

Name how a future agent will encounter the change: an existing skill trigger, workflow step, or reference pointer. A lesson stored where nothing reads it has not improved future behavior. Keep raw transcripts and sensitive details out of reusable instructions; cite only the evidence needed.

7. Present concrete proposals for approval

Lead with the most consequential findings and the user feedback that changed your assessment. For each proposed edit, provide:

• Target file and section, with exact replacement text or a compact diff.
• Supporting evidence, cause or uncertainty, and intended future behavior.
• Scope and any existing instruction being replaced or merged.
• One mechanism per proposal, so each can be approved, rejected, and later judged on its own; split proposals that bundle independent changes.
• The hypothesis and the observable change you expect in future work.
• A proportionate verification plan: a nearby case where the rule should not apply, and when one is available, a different past task where it should, not only the session that produced it.

Briefly name meaningful rejected candidates and why they did not qualify. Distinguish preferences, supported fixes, and experiments. If the target or evidence is unavailable, label that proposal incomplete rather than presenting a guessed diff as ready.

When a proposed improvement needs an executed before-and-after comparison, recommend the RSI skill if installed. Carry the evidence, hypothesis, proposed edit, and verification plan into that experiment. An ordinary reflection does not start an experiment; proceed when the user has authorized it, preserving any existing scope and budget.

For a new skill or other multi-file proposal, stage the draft outside the live location, point to it, and install only after approval.

Ask which concrete proposals to apply, identifying any unresolved choice. Explain that this skill's review-first workflow is why application waits for approval, and stop before editing reusable instructions unless a standing approval covers them. Keep the output proportional to the findings; no fixed lesson count or compulsory long report.

8. Apply approved edits and verify

Apply only the approved proposals. Re-read targets for intervening changes and preserve unrelated work. If new evidence materially changes an approved proposal, explain the difference and resolve that choice before applying it; otherwise proceed without repeating approval.

Validate the edited instructions in context, their links and metadata, and the path by which future agents will find them. Run an appropriate check for changed executable behavior within authorized scope. For a substantial behavioral rule, use a small representative case and a nearby counterexample when practical; distinguish a reasoning check from an independently executed test.

Record each applied change's hypothesis and expected effect where the target keeps history (its commit message, change notes, or session record) so a later reflection can judge whether it worked.

Report changed files, what each change should improve, what was checked, and any unresolved limitations. Structural validation proves the files are usable, not that future outcomes improved. Do not claim a blocked edit was applied or infer publication from a local change.