session-reflection

name: session-reflection description: Use at the end of every team session or work session to record mistakes, lessons, and patterns to .claude.md for self-evolution across sessions

Session Reflection: Self-Evolution Protocol

Overview

Record what went wrong, what went right, and what to change. Persist to .claude.md so future sessions learn from past experience. This is the Agile Retrospective applied to AI agent sessions.

Core principle: Every session that ends without recording its lessons wastes the learning. .claude.md is the team's persistent memory.

Management theory: Agile Retrospectives (continuous improvement), Psychological Safety (honest error reporting), PDCA cycle (Plan-Do-Check-Act).

When to Use

ALWAYS at the end of:

• Any agent team session
• Any session where mistakes were made
• Any session where a valuable method was discovered
• Any debugging session (record eliminated hypotheses)

What to Record

1. Human Instruction Errors

Incorrect, ambiguous, or misleading instructions from the human that led agents astray.

Format:

## Human Instruction Pitfall — [DATE]
**What happened:** [The instruction and how it was misinterpreted]
**Impact:** [What went wrong as a result]
**How to avoid:** [How agents should handle similar instructions]

Examples:

• Human said "fix the tests" but meant "update test expectations"
• Human said "refactor this" but didn't specify which aspect
• Human gave conflicting requirements between two messages

Important: This is NOT blaming the human. It's recording ambiguity patterns so agents can ask clarifying questions next time.

2. Agent Mistakes

Errors made by agents during the session.

Format:

## Agent Mistake — [DATE]
**What happened:** [The mistake]
**Why it happened:** [Root cause — not just "I was wrong"]
**How it was discovered:** [What revealed the mistake]
**How it was resolved:** [The fix]
**How to prevent:** [Specific rule or check to avoid recurrence]

Categories of agent mistakes:

• Confirmation bias (anchored on first explanation)
• Scope creep (built more than requested)
• File conflicts (two agents editing same file)
• Skipped verification (claimed done without testing)
• Contract violation (didn't follow agreed interface)
• Communication gap (didn't share critical finding)

3. Valuable Methods

Techniques or patterns that worked well and should be reused.

Format:

## Effective Method — [DATE]
**Scenario:** [When this method applies]
**Method:** [What to do]
**Why it works:** [The principle behind it]

The Reflection Process

Step 1: Gather Evidence

Before reflecting, collect:

• Task completion status (what got done, what didn't)
• Communication log (messages between agents)
• Conflicts encountered and how resolved
• Unexpected obstacles
• Time sinks

Step 2: Categorize

Sort findings into three buckets:

1. What worked → record as Effective Methods
2. What didn't work → record as Agent Mistakes or Instruction Pitfalls
3. What to change → record as specific preventive rules

Step 3: Write to .claude.md

Append findings to the project's .claude.md file.

Structure in .claude.md:

# Team Orchestrator — Session Learnings

## Instruction Pitfalls (Human → Agent)
[accumulated entries]

## Agent Mistakes
[accumulated entries]

## Effective Methods
[accumulated entries]

## Rules Derived from Experience
[accumulated concrete rules]

Step 4: Promote Universal Lessons

If a lesson applies across ALL projects (not project-specific):

• Also record it in ~/.claude/CLAUDE.md
• These are rare — most lessons are project-specific

Promotion criteria:

• Applies to any codebase, any language
• Not tied to specific project architecture
• Has been confirmed across 2+ sessions

Second-Offense Rule

If an agent makes the same mistake twice:

1. The first occurrence is recorded normally
2. The second occurrence MUST be recorded with emphasis in .claude.md:

## REPEATED MISTAKE — [DATE]
**This mistake has occurred before.** See entry from [PREVIOUS DATE].
**Previous prevention rule failed because:** [why the rule didn't work]
**Updated prevention rule:** [stronger, more specific rule]

This escalation ensures recurring mistakes get stronger guardrails.

Session Start Protocol

At the start of every session:

1. Read .claude.md in the project root
2. Check for relevant past mistakes and rules
3. Apply preventive rules proactively

The SessionStart hook (hooks/session-start.sh) ensures this happens automatically.

Example .claude.md Entries

## Agent Mistake — 2025-11-15
**What happened:** Debugger agent claimed "tests pass" without running them
**Why:** Agent extrapolated from code changes instead of verifying
**Discovered:** Coordinator ran tests independently, found 3 failures
**Resolved:** Forced agent to re-run tests and fix failures
**Prevent:** NEVER claim tests pass without showing test output in response

## Instruction Pitfall — 2025-11-15
**What happened:** Human said "optimize the database queries" — agent rewrote
the entire data access layer instead of optimizing the slow queries
**Impact:** 4 hours of unnecessary refactoring, broke existing tests
**Avoid:** When instructions say "optimize X", ask which specific parts
before starting. Scope to measurably slow areas only.

## Effective Method — 2025-11-15
**Scenario:** Debugging performance issue with multiple possible causes
**Method:** Use competing-hypotheses pattern with 3+ debuggers
**Why it works:** Prevents anchoring on first plausible cause. Devil-advocate
caught that the "obvious" fix was masking the real root cause.

Common Mistakes in Reflection

Integration

Triggered by: All team-orchestrator team patterns at their Adjourning phase Reads: .claude.md in project root Writes to: .claude.md in project root Optionally writes to: ~/.claude/CLAUDE.md for universal lessons