Summarize

Produce an accurate, structured record of session execution. Write for two consumers: the user who verifies changes and a subsequent agent session that continues the work without rediscovery.

Modes

Declare the active operating mode before executing any steps:

• Summary mode (default): Distill session activities, modifications, and findings into structured evidence tables. Run Steps 1 through 3 sequentially and emit .agents/state/summarize/session-summary.md.
• Incident and handoff mode: Package system state, active variables, and failure timelines for incident audits or agent handoffs. Run Steps 1 through 4 sequentially and emit .agents/state/summarize/incident.json alongside the summary document.

Integrity rule

Report exclusively what occurred during the current session:

• Inspect diffs directly; never claim a file changed without inspecting diffs.
• Observe clean terminal output directly; never state a test passed without observing clean terminal output.
• Record verified facts and actual results; never present plans or proposals as completed modifications.
• Record failures, discarded attempts, and dead ends so future sessions do not repeat them.
• Flag unverified paths explicitly instead of assuming success.

Inspect actual repository and working tree state before drafting:

git status --short
git diff --stat
git log --oneline -n 5

If the session produced no code modifications, state this directly.

Workflow

Follow these four steps in sequence:

Step 1. State reconnaissance and evidence extraction

Run status, diff, and log commands to inspect the exact working tree changes and recorded command runs from the session.

Completion criterion. .agents/state/summarize/state-inventory.json exists on disk with modified_files, created_files, deleted_files, and executed_commands.

Step 2. Synthesize actions and root causes

Draft overview, chronological actions table, and root-cause breakdowns citing concrete file paths and test outputs.

Completion criterion. Chronological actions and resolved issues drafted with zero unverified claims and zero omitted failures.

Step 3. Tabulate verification and gaps

Construct the verification evidence table and document known gaps, unverified edge cases, and next steps plainly.

Completion criterion. .agents/state/summarize/session-summary.md exists on disk containing the verification evidence table with exact exit codes and unverified items explicitly cataloged.

Step 4. Context handoff assembly

When operating in Incident and handoff mode, package system state, branch pointers, entry points, and root-cause details into machine-readable handoff artifacts.

Completion criterion. .agents/state/summarize/incident.json exists on disk recording incident_trigger, root_cause, preventive_rule, and handoff_block.

Execution summary structure

Render sections in sequence. Omit a section only when empty, stating the omission explicitly:

1. Overview

Two to three sentences stating session purpose, final status, and present state. The first sentence must answer whether the objective was met.

2. Actions taken

List chronological operations with concrete evidence in a table:

3. Issues and root causes

Document every encounter with bugs or failures:

• Symptom: Observed error text and stack traces.
• Root cause: Underlying system defect and mechanism.
• Evidence: File path, line number, or command output proving the root cause.
• Fix: Architectural modification addressing the root cause.
• Verification: Command executed to validate the fix.

4. Verification evidence table

Record verification commands with exact output:

5. Known gaps and unverified items

State gaps without softening: untested code paths, unverified deployment steps, or open questions requiring decisions.

6. Actionable next steps

Numbered list of concrete next tasks.

7. Agent handoff block

Append this structured block for subsequent agents:

## Context handoff
**State** Completed feature implementation, pending PR creation.
**Branch** `feat/session-refresh`
**Entry point** `src/auth/session.ts`
**Verification command** `npm test && npm run build`
**Open tasks** Caller migration documented in next steps.
**Caution** Do not revert schema migration timestamp constraint.

Anti-patterns

Boundary isolation

Summarization operates strictly in an analytical and reporting capacity. Never edit application code, alter configuration files, or execute mutating commands while creating summaries.

Quick audit checklist

Audit summaries against this table before finalizing: