/session-management

name: session-management
description: Context preservation, tiered summarization, resumability
when-to-use: At session checkpoints, after completing major tasks, or when resuming work
user-invocable: false
effort: low

Session Management Skill

For maintaining context across long development sessions and enabling seamless resume after breaks.

---

Core Principle

**Checkpoint at natural breakpoints, resume instantly.**

Long development sessions risk context loss. Proactively document state, decisions, and progress so any session can resume exactly where it left off - whether returning after a break or hitting context limits.

---

Tiered Summarization Rules

Tier 1: Quick Update (current-state.md only)

**Trigger**: After completing any small task or todo item **Action**: Update "Active Task", "Progress", and "Next Steps" sections **Time**: ~30 seconds

Tier 2: Full Checkpoint (current-state.md + decisions.md)

**Trigger**:

• After completing a feature or significant change
• After any architectural/library decision
• After ~20 tool calls during active work
• When switching to a different area of the codebase

**Action**: 1. Update full current-state.md 2. Log any decisions to decisions.md 3. Update files being modified table

Tier 3: Session Archive (archive/ + full checkpoint)

**Trigger**:

• End of work session
• Completing a major feature/milestone
• Before a significant context shift
• When context feels heavy (~50+ tool calls)

**Action**: 1. Create archive entry: `archive/YYYY-MM-DD[-topic].md` 2. Full checkpoint 3. Clear verbose notes from current-state.md 4. Update code-landmarks.md if new patterns introduced

Decision Heuristic

┌─────────────────────────────────────────────────────┐
│ After completing work, ask:                         │
├─────────────────────────────────────────────────────┤
│ Was a decision made?        → Log to decisions.md   │
│ Task took >10 tool calls?   → Full Checkpoint       │
│ Major feature complete?     → Archive               │
│ Ending session?             → Archive + Handoff     │
│ Otherwise                   → Quick Update          │
└─────────────────────────────────────────────────────┘

---

Session State Structure

Create `_project_specs/session/` directory:

_project_specs/
└── session/
    ├── current-state.md      # Live session state (update frequently)
    ├── decisions.md          # Key decisions log (append-only)
    ├── code-landmarks.md     # Important code locations
    └── archive/              # Past session summaries
        └── 2025-01-15.md

---

Current State File

**`_project_specs/session/current-state.md`** - Update every 15-20 minutes or after significant progress.

# Current Session State

*Last updated: 2025-01-15 14:32*

## Active Task
[One sentence: what are we working on right now]

Example: Implementing user authentication flow with JWT tokens

## Current Status
- **Phase**: [exploring | planning | implementing | testing | debugging | refactoring]
- **Progress**: [X of Y steps complete, or percentage]
- **Blocking Issues**: [None, or describe blockers]

## Context Summary
[2-3 sentences summarizing the current state of work]

Example: Created auth middleware and login endpoint. JWT signing works.
Currently implementing token refresh logic. Need to add refresh token
rotation for security.

## Files Being Modified
| File | Status | Notes |
|------|--------|-------|
| src/auth/middleware.ts | Done | JWT verification |
| src/auth/refresh.ts | In Progress | Token rotation |
| src/auth/types.ts | Done | Token interfaces |

## Next Steps
1. [ ] Complete refresh token rotation in refresh.ts
2. [ ] Add token blacklist for logout
3. [ ] Write integration tests for auth flow

## Key Context to Preserve
- Using RS256 algorithm (not HS256) per security requirements
- Refresh tokens stored in HttpOnly cookies
- Access tokens: 15 min, Refresh tokens: 7 days

## Resume Instructions
To continue this work:
1. Read src/auth/refresh.ts - currently at line 45
2. The rotateRefreshToken() function needs error handling
3. Check decisions.md for why we chose RS256 over HS256

---

Decision Log

**`_project_specs/session/decisions.md`** - Append-only log of architectural and implementation decisions.

# Decision Log

Track key decisions for future reference. Never delete entries.

---

## [2025-01-15] JWT Algorithm Choice

**Decision**: Use RS256 instead of HS256 for JWT signing

**Context**: Implementing authentication system

**Options Considered**:
1. HS256 (symmetric) - Simpler, single secret
2. RS256 (asymmetric) - Public/private key pair

**Choice**: RS256

**Reasoning**:
- Allows token verification without exposing signing key
- Better for microservices (services only need public key)
- Industry standard for production systems

**Trade-offs**:
- Slightly more complex key management
- Larger token size

**References**:
- src/auth/keys/ - Key storage
- docs/security.md - Security architecture

---

## [2025-01-14] Database Schema Approach

**Decision**: Use Drizzle ORM with PostgreSQL

**Context**: Setting up data layer

**Options Considered**:
1. Prisma - Popular, good DX
2. Drizzle - Type-safe, SQL-like
3. Raw SQL - Maximum control

**Choice**: Drizzle

**Reasoning**:
- Better TypeScript inference than Prisma
- More transparent SQL generation
- Lighter weight, faster cold starts

**References**:
- src/db/schema.ts - Schema definitions
- src/db/migrations/ - Migration files

---

Code Landmarks

**`_project_specs/session/code-landmarks.md`** - Important code locations for quick reference.

# Code Landmarks

Quick reference to important parts of the codebase.

## Entry Points
| Location | Purpose |
|----------|---------|
| src/index.ts | Main application entry |
| src/api/routes.ts | API route definitions |
| src/workers/index.ts | Background job entry |

## Core Business Logic
| Location | Purpose |
|----------|---------|
| src/core