project-session-management

What this skill does

# Project Session Management Skill

You are a session management assistant. Your role is to help developers track progress across multiple work sessions and manage context efficiently when working on phased projects.

---

## ⚡ When to Use This Skill

Use this skill when:
- **Starting a new project** after `project-planning` skill has generated IMPLEMENTATION_PHASES.md
- **Resuming work** after clearing context or starting a fresh session
- **Mid-phase checkpoint** when context is getting full but phase isn't complete
- **Phase transitions** moving from one phase to the next
- **Tracking verification** managing the Implementation → Verification → Debugging cycle

---

## Core Concept: Phases vs Sessions

Understanding the difference between phases and sessions is critical:

### Phases (from IMPLEMENTATION_PHASES.md)
- **Units of WORK** (e.g., "Database Schema", "Auth API", "Task UI")
- Defined in planning docs
- Have verification criteria and exit criteria
- Ideally fit in one session, but may span multiple if complex

### Sessions (what this skill manages)
- **Units of CONTEXT** (what you accomplish before clearing/compacting context)
- Tracked in SESSION.md
- Can complete a phase, part of a phase, or multiple small phases
- Bridges work across context window limits

**Example**:
```
Phase 3: Tasks API (estimated 4 hours)
  Session 1: Implement GET/POST endpoints → context full, checkpoint
  Session 2: Implement PATCH/DELETE → context full, checkpoint
  Session 3: Fix bugs, verify all criteria → Phase 3 complete ✅
```

---

## ⭐ Recommended Workflow

### When Starting a New Project

1. ✅ User has run `project-planning` skill (IMPLEMENTATION_PHASES.md exists)
2. ✅ **Offer to create SESSION.md**: "Would you like me to create SESSION.md to track progress?"
3. ✅ **Generate SESSION.md** from IMPLEMENTATION_PHASES.md phases
4. ✅ **Set Phase 1 as current** with status 🔄 (in progress)
5. ✅ **Set concrete "Next Action"** for Phase 1
6. ✅ **Output SESSION.md** to project root

### Before Ending Any Session

1. ✅ **Update SESSION.md** with current phase progress
2. ✅ **Create git checkpoint commit** (see format below)
3. ✅ **Update "Next Action"** to be concrete (file + line + what to do)

### When Resuming

1. ✅ **Read SESSION.md** to understand current state
2. ✅ **Check "Next Action"** for concrete starting point
3. ✅ **Continue from that point**

---

## SESSION.md Structure

### Purpose
**Navigation hub** that references planning docs and tracks current progress

**Target Size**: <200 lines
**Location**: Project root
**Update Frequency**: After significant progress (not every tiny change)

### Template

```markdown
# Session State

**Current Phase**: Phase 3
**Current Stage**: Implementation (or Verification/Debugging)
**Last Checkpoint**: abc1234 (2025-10-23)
**Planning Docs**: `docs/IMPLEMENTATION_PHASES.md`, `docs/ARCHITECTURE.md`

---

## Phase 1: Setup ✅
**Completed**: 2025-10-15 | **Checkpoint**: abc1234
**Summary**: Vite + React + Tailwind v4 + D1 binding

## Phase 2: Database ✅
**Completed**: 2025-10-18 | **Checkpoint**: def5678
**Summary**: D1 schema + migrations + seed data

## Phase 3: Tasks API 🔄
**Type**: API | **Started**: 2025-10-23
**Spec**: `docs/IMPLEMENTATION_PHASES.md#phase-3`

**Progress**:
- [x] GET /api/tasks endpoint (commit: ghi9012)
- [x] POST /api/tasks endpoint (commit: jkl3456)
- [ ] PATCH /api/tasks/:id ← **CURRENT**
- [ ] DELETE /api/tasks/:id
- [ ] Verify all endpoints (see IMPLEMENTATION_PHASES.md for criteria)

**Next Action**: Implement PATCH /api/tasks/:id in src/routes/tasks.ts:47, handle validation and ownership check

**Key Files**:
- `src/routes/tasks.ts`
- `src/lib/schemas.ts`

**Known Issues**: None

## Phase 4: Task UI ⏸️
**Spec**: `docs/IMPLEMENTATION_PHASES.md#phase-4`
```

---

## Status Icons

Use these emoji status icons consistently:

- **⏸️** = Not started (pending)
- **🔄** = In progress
- **✅** = Complete
- **🚫** = Blocked

---

## Stages Within a Phase

Track where you are in the build-test-fix cycle:

1. **Implementation** → Writing code for tasks
2. **Verification** → Testing against verification criteria
3. **Debugging** → Fixing issues found during verification

**Update SESSION.md** to reflect current stage:

```markdown
**Current Stage**: Verification

**Verification Progress**:
- [x] GET /api/tasks returns 200 ✅
- [x] POST /api/tasks creates task ✅
- [ ] POST with invalid data returns 400 ❌ (returns 500)
- [ ] PATCH updates task
- [ ] DELETE removes task

**Current Issue**: Invalid data returning 500 instead of 400. Need to check validation middleware in src/middleware/validate.ts
```

**Why this matters**: Makes troubleshooting part of the normal flow, not an interruption. Users can resume knowing exactly where debugging left off.

---

## Rules for SESSION.md

### ✅ DO

- **Collapse completed phases** to 2-3 lines (save space)
- **Make "Next Action" concrete** (file + line + what to do)
- **Reference planning docs**, don't duplicate them
- **Update after significant progress** (not every tiny change)
- **Create git checkpoint** at end of phase OR when context is getting full
- **Track verification progress** when in that stage

### ❌ DON'T

- **Copy code** into SESSION.md (it's a tracker, not a code archive)
- **Duplicate IMPLEMENTATION_PHASES.md** content (just reference it)
- **Use vague next actions** ("Continue working on API..." is too vague)
- **Let SESSION.md exceed 200 lines** (archive old phases if needed)

---

## Git Checkpoint Format

Use this structured format for checkpoint commits:

```
checkpoint: Phase [N] [Status] - [Brief Description]

Phase: [N] - [Name]
Status: [Complete/In Progress/Paused]
Session: [What was accomplished this session]

Files Changed:
- path/to/file.ts (what changed)

Next: [Concrete next action]
```

### Examples

#### Phase Complete
```
checkpoint: Phase 3 Complete - Tasks API

Phase: 3 - Tasks API
Status: Complete
Session: Completed all CRUD endpoints and verified functionality

Files Changed:
- src/routes/tasks.ts (all CRUD operations)
- src/lib/schemas.ts (task validation)
- src/middleware/validate.ts (validation middleware)

Next: Phase 4 - Start building Task List UI component
```

#### Context Full Mid-Phase
```
checkpoint: Phase 3 In Progress - Endpoints implemented

Phase: 3 - Tasks API
Status: In Progress
Session: Implemented GET and POST endpoints, need PATCH/DELETE

Files Changed:
- src/routes/tasks.ts (GET, POST endpoints)
- src/lib/schemas.ts (task schema)

Next: Implement PATCH /api/tasks/:id in src/routes/tasks.ts:47
```

#### Blocked or Paused
```
checkpoint: Phase 3 Paused - Need design decision

Phase: 3 - Tasks API
Status: Paused
Session: Built endpoints but need to decide on tag filtering approach

Files Changed:
- src/routes/tasks.ts (basic endpoints)

Next: Decide: client-side tag filtering or add SQL query parameter? Then resume at src/routes/tasks.ts:89
```

---

## Context Management Strategies

### When Context is Getting Full (but phase isn't done)

1. ✅ Update SESSION.md with current progress
2. ✅ Create checkpoint commit
3. ✅ Clear context or start fresh session
4. ✅ Read SESSION.md + referenced planning docs
5. ✅ Continue from "Next Action"

### When a Phase is Complete

1. ✅ Check all verification criteria in IMPLEMENTATION_PHASES.md
2. ✅ Mark phase complete in SESSION.md (change 🔄 to ✅)
3. ✅ Create checkpoint commit
4. ✅ Move to next phase (change next phase from ⏸️ to 🔄)

### When Troubleshooting Takes Over

- ✅ Don't fight it - update SESSION.md to show "Debugging" stage
- ✅ Document the issue in "Current Issue" field
- ✅ When fixed, move back to "Verification" or "Implementation"

---

## Integration with project-planning Skill

The `project-planning` skill and this skill work together:

```
project-planning skill
        ↓
Generates IMPLEMENTATION_PHASES.md (the plan)
        ↓
project-session-management skill
        ↓
Creates SESSION.md (the tracker)
        ↓
Work through phases, updating SESSION.md
        ↓