| name | session-retro |
| description | Distill session learnings back into the repository before ending a session. Use at the end of sessions involving bug fixes, feature implementation, or debugging. Classifies learnings as gotcha (external pitfall) or harness (AI behavior improvement) and appends to appropriate harness components. Most effective when called just before commit/PR creation or as a completion signal. |
| user-invocable | true |
Session Retro
A triage skill that distills session learnings back into the repository.
Why Persist to the Repository
Local memory only affects personal conversation context. Repository-persisted learnings benefit CI, other agents, and all future sessions.
Classification Criteria
| Category | Definition | Example |
|---|
| gotcha | Non-intuitive behavior of external frameworks, libraries, or runtimes | "SQLite's CURRENT_TIMESTAMP is UTC" |
| harness | Insights that improve AI agent behavior | "Verify bugs on device before code fixes" |
| skip | Basic knowledge, temporary state, or things sufficiently captured in code | "React useState is independent" |
Choosing Where to Save Harness Learnings
| Nature of Learning | Destination | Example |
|---|
| Always-applicable conventions | .claude/rules/<topic>.md | "Verify bugs on device" |
| Project-wide policy changes | CLAUDE.md | Adding new tools |
| Reusable workflows | .claude/skills/ | Deploy procedures |
| Automatically enforced rules | hooks in .claude/settings.json | Format enforcement |
Steps
-
Read current state — Review docs/gotchas.md and .claude/rules/ existing entries
-
Review the session — Extract learning candidates from conversation context:
- Errors encountered and their workarounds
- Gaps between documentation and actual behavior
- Correction instructions from the user
- Non-obvious behaviors discovered during debugging
-
Classify and present — Classify candidates and ask user for confirmation:
Organized session learnings:
[gotcha]
1. [Category] Description -> Workaround
[harness]
2. Description -> Destination: <path>
[skip]
3. Description (reason: basic knowledge)
Select which to add.
-
Duplicate check — Verify no overlap with existing entries
-
Append — Add gotchas to docs/gotchas.md, harness learnings to selected destination
Notes
- Never add entries without user confirmation
- Show reasoning for skip classifications (transparency for user override)
