session-self-analysis

name	session-self-analysis
description	Agent session self-analysis workflow. Use at the end of a session or after user feedback to identify process failures, perform 5 Whys, and record durable learnings without duplicates. Trigger when: /self-analysis, self analysis, session retrospective, session learnings.

Session Self-Analysis Skill

Analyze the current agent session and record durable lessons when needed.

Contract

• Input: current session context and optional user feedback.
• Output: concise self-analysis and any memory/skill updates.
• Side effects: may edit .claude/memory/, a project session-learnings file (if one exists), or a relevant .agent/skills/*/SKILL.md after deduplication.

Workflow

1. Review Signals

Look for:

• user had to clarify the request
• user asked for format/style changes
• factual correction was needed
• repeated instructions were missed
• CI/review bots caught issues from this session
• repo rules were missed or applied late

If no friction occurred, say so briefly and stop.

2. Categorize

Use:

• Format: structure, length, style
• Substance: factual error or missed repo pattern
• Tone: too formal/casual or wrong language
• Logic: flawed reasoning or missed instruction
• Process: wrong tool order, missing pre-flight, bad Git/PR flow

3. 5 Whys

For the most important issue, ask why until the root cause is specific and actionable. Three to five steps are enough.

4. Formulate Rule

Good rule format:

[Trigger/context] -> [Expected behavior]

Rules must be concrete and testable. Avoid vague rules like "be more careful".

5. Deduplicate Before Writing

Search:

ls .claude/memory
rg -n "keyword|concept" .claude/memory .agent/skills

Destination:

Type	Destination
process/workflow feedback	.claude/memory/feedback_*.md
code-level gotcha	project session-learnings file (if maintained)
domain-specific rule	relevant .agent/skills/*/SKILL.md

If an existing file covers the concept, update it rather than creating a duplicate.

6. Memory File Format

---
name: short-rule-name
description: One-line description
type: feedback
---

Rule statement.

**Why:** Incident that caused this rule.

**How to apply:** Trigger and concrete behavior.

After creating a memory file, add a one-line pointer to .claude/memory/MEMORY.md (or the equivalent index in your project).

Rules

• Use bullet points, not numbered lists, inside memory files.
• Do not create root-level docs.
• Do not record generic preferences that are already covered by the repo's AGENTS.md / CLAUDE.md.
• Memory recorded in .claude/memory/ is the repo SSOT shared across Claude / Codex / Copilot sessions. Per-machine user memory (~/.claude/projects/.../memory/ for Claude Code) is invisible to other agents — only sync rules worth sharing.