Session Reflection Skill

Description

This skill reviews the current or recent Claude Code session, extracts lessons learned, and updates your project's CLAUDE.md file with new rules and patterns. It turns one-off corrections into persistent knowledge.

Instructions

When the user asks you to reflect on the session or update CLAUDE.md, follow this workflow:

Step 1: Session Analysis

Review the conversation history and identify:

Copy
## Session Analysis

### What Worked Well
- Used `exceljs` for spreadsheet generation — worked first try
- File search strategy: started with glob, narrowed with grep
- Incremental commits after each feature

### What Failed / Required Correction
- Tried to use `fs.writeFileSync` for streaming large file — caused OOM
  - **Lesson:** Use streams for files > 50MB
- Forgot to check for existing `.env` before creating new one
  - **Lesson:** Always check if config files exist before writing
- Used `any` type in TypeScript — user corrected
  - **Lesson:** User prefers strict typing, no `any` allowed

### Patterns Discovered
- Project uses barrel exports (index.ts) in every directory
- Tests follow `*.spec.ts` naming (not `*.test.ts`)
- API routes follow `/api/v2/{resource}` convention
- Error responses use `{ error: string, code: number }` shape

Step 2: Draft CLAUDE.md Updates

Propose additions to the project's CLAUDE.md:

Copy
## Proposed Additions to CLAUDE.md

### Code Style
- Use strict TypeScript — never use `any` type
- Test files use `*.spec.ts` naming convention
- Every directory has a barrel export `index.ts`

### Architecture
- API routes: `/api/v2/{resource}` convention
- Error response shape: `{ error: string, code: number }`
- Use streams for file operations > 50MB

### Workflow
- Always check if config files exist before creating
- Commit incrementally after each logical change

Step 3: Apply Updates

After user approval:

• Read existing CLAUDE.md
• Merge new rules without duplicating existing ones
• Organize by category
• Write updated file

Rules

• Only add rules that came from actual corrections or discoveries during the session
• Do not add generic best practices — only project-specific learnings
• Check for duplicates before adding to CLAUDE.md
• Present proposed changes to the user before writing
• Keep rules concise and actionable — one line each when possible
• Group related rules under descriptive headings
• Remove or update rules that contradict new learnings
• Date-stamp significant additions with a comment

Examples

User: Reflect on this session Action: Analyze conversation, present findings, propose CLAUDE.md updates

User: What did you learn from our work today? Action: Summarize patterns, mistakes, and corrections discovered

User: Update CLAUDE.md with what we learned Action: Review session, draft additions, apply after confirmation