Menu
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
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Use when facing a task that could benefit from parallel work - decides whether to use subagents or agent teams, then composes the right team from the role pool based on task analysis
Use when debugging with unclear root cause and multiple plausible explanations that need parallel adversarial testing to converge on the answer
Use when changes span frontend, backend, and tests where each layer needs a dedicated owner plus an integration agent for cross-cutting consistency
Use when building new modules or features where teammates can each own a separate piece without stepping on each other
Use when multiple aspects of a problem need parallel investigation with findings shared and challenged between investigators
| 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 |
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).
ALWAYS at the end of:
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:
Important: This is NOT blaming the human. It's recording ambiguity patterns so agents can ask clarifying questions next time.
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:
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]
Before reflecting, collect:
Sort findings into three buckets:
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]
If a lesson applies across ALL projects (not project-specific):
~/.claude/CLAUDE.mdPromotion criteria:
If an agent makes the same mistake twice:
.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.
At the start of every session:
.claude.md in the project rootThe SessionStart hook (hooks/session-start.sh) ensures this happens automatically.
## 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.
| 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 |
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