| 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:
- What worked → record as Effective Methods
- What didn't work → record as Agent Mistakes or Instruction Pitfalls
- 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:
- The first occurrence is recorded normally
- 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:
- Read
.claude.md in the project root
- Check for relevant past mistakes and rules
- 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
| Mistake | Fix |
|---|
| Too vague: "we made mistakes" | Specific: what, why, how discovered, how to prevent |
| Blaming human instructions | Neutral: record the ambiguity pattern, not blame |
| Not reading .claude.md at session start | Hook enforces this |
| Recording too much | Only record actionable items with preventive rules |
| Never promoting to global CLAUDE.md | Review after 5+ sessions for universal patterns |
| Not updating when rules fail | Second-offense protocol handles this |
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
