Session Refiner

Automatically create a compact bridge between long coding sessions to minimize token usage and costs while preserving essential context.

Quick Start

When your conversation is getting long:

You: "Use Session Refiner to create a summary"
Claude: [Generates compact markdown summary and automatically saves it]
You: [Start fresh chat, paste summary at top of conversation]

That's it. You've reset your context window while keeping continuity.

Automatic Saving: Summaries are automatically saved to .claude/session-summaries/ with timestamped filenames like 20251220-data-cleaning-plan.md for easy reference and organization.

What Gets Extracted

Active Tasks

• Unchecked items from your todo list
• TODOs and FIXMEs from code
• Stated next steps and remaining work

Key Technical Decisions

• Architectural choices made (JWT vs sessions, database selection, etc.)
• Design patterns chosen and why
• Rejected alternatives

Resolved Issues

• Bugs that were fixed
• Errors that were debugged
• Problems that were solved

Code References

• Essential snippets (not full files)
• Recently-changed patterns
• Important configurations
• File paths for context

Key Findings

• Important discoveries
• Important notes and reminders
• Non-obvious insights

Workflow

Option 1: Ask Claude (Easiest)

Say in your chat: "Use Session Refiner to create a summary"

Claude will:

1. Scan the current conversation for key information
2. Extract essential details only
3. Generate a markdown summary
4. Automatically save it to .claude/session-summaries/YYYYMMDD-brief-title.md
5. Display the file path

Then:

1. Start a new chat session
2. Paste the summary at the top (or reference the file path in .claude/session-summaries/)
3. Say: "Here's where I left off. Continue from here."
4. Resume work with fresh context window

Option 2: Run Script Locally (Most Control)

For maximum clarity, export your conversation and run the extraction script:

# Manually save conversation to a text file, then:
python .claude/skills/session-refiner/scripts/extract_session_summary.py \
  conversation.txt \
  --output my-summary.md \
  --max-tokens 5000

The script parses:

• Explicit TODO: and FIXME: markers
• Unchecked checkboxes: - [ ] task
• Code blocks (triple backticks)
• Decision statements: "Decided to...", "Using...", etc.
• Bug resolutions: "Fixed:", "Resolved:"

Edit the output markdown if needed, then paste into a fresh chat.

When to Use

Milestones:

• Completing a major feature → summarize, start fresh for next feature
• After intense debugging → capture what was learned, move on
• Switching between codebases/projects → snapshot state, fresh session

Token Warnings:

• Claude mentions "conversation getting long"
• You see context window warnings
• You've had multiple back-and-forth debugging rounds

Cost Optimization:

• Before a pause in work (stop for the day)
• Before switching to a different developer/session
• When you notice the conversation history exceeding 50k tokens

Token Budget

A complete summary uses 2,000–5,000 tokens, leaving you:

• Session 1: 100k tokens used in long conversation
• Summary: 3,500 tokens
• Session 2: Start fresh with 3,500 tokens used, 196,500 tokens available

Without refining, Session 2 would start with 100k tokens already consumed.

Best Practices

1. Be explicit in chat: Use clear markers in conversation:

   TODO: Fix login validation
   FIXME: Error handling in API
   - [ ] Add unit tests
   

   These make extraction more accurate.

2. Review before reuse: Skim the generated summary before pasting. Edit if anything seems incomplete or unclear.

3. Keep originals: Store full conversations separately in case you need to reference them later.

4. Extract at good moments: Extract after finishing a module, feature, or debugging session—not randomly mid-task.

5. Add context notes: If something in the summary seems vague, add a clarifying note directly in the markdown before pasting.

Example Summary Output

# Session Summary
**Generated**: 2025-12-18 14:30:00

## Current Status

### Active Tasks
- [ ] Add authentication middleware
- [ ] Implement password reset flow
- [ ] Write integration tests for auth

## Key Technical Decisions
- **JWT tokens with refresh rotation** for stateless auth
- **PostgreSQL** for user persistence (transaction support)
- **bcryptjs** for password hashing (OWASP compliant)

## Resolved Issues
- Fixed CORS error by adding credentials flag to fetch
- Resolved password validation regex (Unicode support)

## Code References

### JavaScript
\`\`\`javascript
const hashPassword = async (pw) => {
  return bcrypt.hash(pw, 10);
};
\`\`\`

### SQL
\`\`\`sql
CREATE TABLE users (
  id SERIAL PRIMARY KEY,
  email VARCHAR UNIQUE NOT NULL,
  password_hash VARCHAR NOT NULL
);
\`\`\`

## Key Findings
- Session tokens need 15-min expiry for security
- User table indexes on email for login performance

## Next Steps
1. Review the active tasks above
2. Paste this summary into a fresh chat session
3. Continue from where you left off

How Claude Uses This Skill

When you request a summary, Claude will:

1. Scan the conversation for patterns like:

   • TODO:, FIXME:, [ ] checkboxes → Active Tasks
   • Decision statements → Key Decisions
   • "Fixed", "Resolved" → Resolved Issues
   • Code blocks → Code References
   • Key findings statements → Insights

2. Extract sparingly: Only essential information, not entire files or repetitive content.

3. Generate markdown: Clean, copy-paste-ready format.

4. Automatically save: Write summary to .claude/session-summaries/YYYYMMDD-brief-title.md

   • Format: YYYYMMDD (ISO date) + - + brief title (kebab-case)
   • Example: 20251220-data-cleaning-plan.md
   • Automatically creates directory if needed

5. Hand to you: You can paste the summary content or reference the saved file.

Technical Details

See workflow.md for detailed step-by-step examples and advanced extraction techniques.

The extraction script (scripts/extract_session_summary.py) uses regex patterns to identify:

• Explicit TODO/FIXME markers
• Checkbox lists
• Code blocks with language markers
• Decision and resolution keywords
• Key finding statements

You can manually run it for programmatic extraction when needed.