debrief

name	debrief
description	Post-execution retrospective on an agent run. Compares what the handoff packet predicted against what actually happened — surfaces broken assumptions, unexpected failures, and one concrete change for the next run. Use after an agent completes a task, when the user says "debrief", "retro", "what went wrong", or wants to capture learnings before the next handoff.

debrief

When to use

You ran an agent using an AHA handoff packet (or any structured prompt). The run is done — succeeded, failed, or partially completed. Before you close the ticket or move on, you want to capture what was different from the plan.

Inputs you supply

• The original handoff packet (or the agent prompt section at minimum).
• A short description of what the agent actually did — output produced, errors hit, where it got stuck.
• A return packet.
• (Optional) The agent's raw output or a transcript excerpt if the gap is subtle.

Expected output

Seven sections: what matched, what broke, root causes (ranked), return-packet check, AHA delta, proposed rules, and one concrete change for the next run.

Instructions

You are running a post-execution retrospective. The user will provide a handoff packet and an account of what the agent actually did. Your job is to compare prediction against reality — not to judge the outcome, just to surface the gap clearly.

Hard rules:

• If either the packet or the actual-run description is missing, ask for it and stop. Do not fabricate.
• Do not re-summarize the packet. Identify only the gaps.
• Every point names a specific section of the packet it came from (e.g., "Scope — in scope item 2", "Inputs checklist item 3").
• Do not soften findings. "The agent struggled" is not specific. "The agent looped on step 3 because the retry policy was missing from the inputs checklist" is.
• Output voice — apply these to every line:
  • Flat, direct, concrete. State what happened.
  • Sentence case headings. Minimize bold and em dashes.
  • Banned words: delve, tapestry, vibrant, pivotal, crucial, intricate, landscape (abstract), testament, underscore (verb), meticulous, garner, bolstered, fostering, enhance, showcase, interplay, enduring, nestled, groundbreaking, renowned.
  • Banned phrases: "not just X but Y", "despite challenges", "serves as" (use "is"), section summaries, "it's important to note", promotional puffery.

Output format:

What matched

Up to 3 items. Specific things the packet predicted correctly — assumption held, constraint respected, output matched. One line each with citation.

What broke

Up to 5 items. For each:

• What happened (one sentence)
• Which packet section was wrong or missing
• Severity: H / M / L

Root causes

Ranked list, max 3. Each cause applies to one or more "what broke" items. Name the cause, not the symptom. "Missing input" is a cause. "Agent failed" is a symptom.

Return-packet check

If a return_packet was supplied, set its status: complete | partial | missing | conflicting. A packet that claims no blockers while an acceptance check failed, or lists files_changed with no commands_run, is conflicting and becomes an H-severity item under "What broke".

AHA delta

One line: the specific decision, missing input, approval gate, or validation check that changed because AHA ran. If none, say "no delta — this task did not need AHA."

Proposed rules

Up to 1 by default. For each: the rule text, scope, and provenance (this session + the break it came from). Status is "proposed". Do not edit any instruction file here.

One change for the next run

One paragraph. The single edit to the handoff packet (or the process that produced it) that would have prevented the highest-severity break. Be specific: name the section, the line, what to add or change.

Failure modes

• Debrief re-summarizes the packet instead of diffing against it. Fix: frame every point as "packet said X, reality was Y".
• "What broke" items are vague ("agent got confused"). Fix: require a packet citation per item.
• Root causes duplicate "what broke" items. Fix: causes explain why breaks happened, not what the breaks were.
• "One change" duplicates a "what broke" item. Fix: it must be a prescription (what to write differently), not a description of the failure.

Example invocation

User input:

Packet: agent to triage failed webhook deliveries. In scope: classify failure type, suggest retry. What happened: agent classified correctly but invented a retry URL that doesn't exist. Retries section was empty in the packet. return_packet: status: complete files_changed: [] commands_run: [] acceptance_check_results: - "retry URL verified: fail; no policy source was supplied" blockers: []

Expected output:

What matched

1. Failure classification ran correctly — "Scope — in scope item 1" held.
2. Output was a markdown table as specified — "Agent prompt — output schema" held.

What broke

1. Agent invented a retry endpoint not in the inputs. Inputs checklist had no retry policy document. Severity: H.
2. Output had 14 rows; packet said max 10. "Agent prompt — output schema" cap was not enforced. Severity: M.

Root causes

1. Missing input: retry policy was listed as [SPECIFY: ...] but never filled in before the run.
2. Output cap not enforced: the word "max" in the schema was not backed by a hard instruction.

Return-packet check

Status: conflicting. The packet claims complete and lists no blockers, but the acceptance check failed because the retry policy source was missing.

AHA delta

AHA should have added a stop condition: do not suggest retries until the retry policy excerpt is pasted.

Proposed rules

1. Rule: Handoffs that request retries must include the retry policy excerpt or a stop condition. Scope: coding. Provenance: this session, missing retry policy break. Status: proposed.

One change for the next run

In the Inputs checklist, replace "[SPECIFY: retry policy excerpt]" with a required gate: "Do not start phase 4 until this item is pasted." The agent invented the URL because it had no data and no instruction to stop.