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]
You: [Download summary, start fresh chat, paste at top]

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

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. •You download it

Then:

1. •Start a new chat session
2. •Paste the summary at the top
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:

   code

   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. •

   Hand to you: You control what happens next—download, edit, paste, continue.

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.