gh-jezweb-claude-skills-skills-project-session-management/references/best-practices.md

Session Management Best Practices

When to use, how to maintain, and common patterns for successful session management

---

When to Use Session Management

✅ Use SESSION.md When

• Multi-phase projects (3+ phases)
• Complex implementations (>8 hours total estimated work)
• Frequent context clears (working across multiple sessions)
• Multiple parallel projects (need to switch context often)
• Team collaboration (others need to understand current state)

❌ Skip SESSION.md When

• Single-phase project (<2 hours of work)
• Spike/prototype (exploratory work, not production)
• Quick fix (one-off bug fix or small change)
• Fully completed project (all phases done, no active work)

---

Maintenance Patterns

Update Frequency

Update SESSION.md when:

• ✅ Completing a task within a phase
• ✅ Moving between stages (Implementation → Verification → Debugging)
• ✅ Hitting a blocker or pausing work
• ✅ Completing a phase
• ✅ Context is getting full (need to checkpoint)

Don't update SESSION.md for:

• ❌ Every single line of code
• ❌ Minor refactoring during implementation
• ❌ Fixing typos or formatting
• ❌ Temporary debugging experiments

Rule of thumb: Update after "significant progress" (completing a checklist item, moving stages, or ending session)

---

Git Checkpoint Timing

When to Create Checkpoints

Always checkpoint when:

• ✅ Phase complete (all verification passed)
• ✅ Context getting full (>80% of context window)
• ✅ Pausing work (end of day, switching projects)
• ✅ Hit a blocker (waiting for decision or external input)

Consider checkpointing when:

• ⚡ Finishing a major task (e.g., all CRUD endpoints done)
• ⚡ Switching stages (Implementation → Verification)
• ⚡ After fixing a complex bug

Don't checkpoint:

• ❌ Every commit (checkpoints are milestones, not commits)
• ❌ Work in progress (wait for completed task)
• ❌ Failed experiments (revert instead)

---

Next Action Quality

✅ Good Next Actions (Concrete)

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

• File path: src/routes/tasks.ts
• Line number: 47
• Specific action: "Implement PATCH endpoint"
• Context: "handle validation and ownership check"

**Next Action**: Fix validation bug in src/middleware/validate.ts:23, add try-catch for Zod errors

• Debugging-focused
• Specific file and line
• Clear fix needed

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

• Decision point clearly stated
• Resume point provided
• User knows this is blocked on their choice

❌ Bad Next Actions (Vague)

**Next Action**: Continue working on API

• Which API endpoint?
• Which file?
• What specifically needs to be done?

**Next Action**: Fix bugs

• Which bugs?
• Where are they?
• No concrete starting point

**Next Action**: Finish Phase 3

• What's left to do?
• No specific task
• No file path

---

Status Icon Usage

Phase Status

• ⏸️ Pending - Not started yet, waiting for earlier phases
• 🔄 In Progress - Currently working on this phase
• ✅ Complete - All tasks done, verification passed
• 🚫 Blocked - Cannot proceed due to external blocker

Rules:

• Only ONE phase should be 🔄 at a time (current focus)
• Use 🚫 sparingly (most "blockers" are really pauses)
• Mark ✅ only when verification complete (not just code written)

Task Status

Within a phase's progress checklist:

• - [ ] = Not started
• - [ ] with ← **CURRENT** = Working on this now
• - [x] = Completed
• - [x] with ✅ = Completed and verified

---

Common Patterns

Pattern: Mid-Phase Context Clear

Scenario: Implementing Phase 3, context at 85%, still have 3 tasks left

Action:

1. Update SESSION.md progress (mark completed tasks with [x])
2. Set "Next Action" to next uncompleted task
3. Create checkpoint commit (status: In Progress)
4. Push to remote
5. Clear context
6. New session: Read SESSION.md, go to "Next Action"

Example SESSION.md update:

## Phase 3: Tasks API 🔄
**Progress**:
- [x] GET /api/tasks endpoint (commit: abc123)
- [x] POST /api/tasks endpoint (commit: def456)
- [ ] PATCH /api/tasks/:id ← **CURRENT**
- [ ] DELETE /api/tasks/:id
- [ ] Verify all endpoints

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

---

Pattern: Verification Stage Tracking

Scenario: Phase 3 code complete, now verifying against criteria

Action:

1. Change "Current Stage" to "Verification"
2. Add "Verification Progress" section
3. Check off criteria as you test
4. Note failures with ❌ and description

Example SESSION.md update:

## Phase 3: Tasks API 🔄
**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

Next: Switch to "Debugging" stage, fix the issue, return to "Verification"

---

Pattern: Phase Complete

Scenario: All verification passed, phase is done

Action:

1. Change phase status from 🔄 to ✅
2. Add completion date and checkpoint
3. Collapse to 2-3 lines
4. Change next phase from ⏸️ to 🔄
5. Create checkpoint commit (status: Complete)

Before:

## Phase 3: Tasks API 🔄
**Progress**:
- [x] GET /api/tasks endpoint
- [x] POST /api/tasks endpoint
- [x] PATCH /api/tasks/:id
- [x] DELETE /api/tasks/:id
- [x] Verify all endpoints ✅

**Next Action**: Verify DELETE endpoint

After:

## Phase 3: Tasks API ✅
**Completed**: 2025-10-23 | **Checkpoint**: ghi789
**Summary**: All CRUD endpoints implemented and verified

## Phase 4: Task UI 🔄
**Type**: UI | **Started**: 2025-10-23
**Spec**: `docs/IMPLEMENTATION_PHASES.md#phase-4`
**Next Action**: Create TaskList component in src/components/TaskList.tsx

---

Troubleshooting

Problem: SESSION.md growing too large (>200 lines)

Solution: Archive completed phases

1. Create SESSION_ARCHIVE.md
2. Move completed phases there
3. Keep only current + next 2-3 phases in SESSION.md

Problem: Forgot to update SESSION.md, now out of sync

Solution: Reconstruct from git history

1. Look at recent commits
2. Update SESSION.md to match actual state
3. Set concrete "Next Action"
4. Create checkpoint commit to establish baseline

Problem: Next Action is now wrong (changed approach)

Solution: Update immediately

1. Change "Next Action" to reflect new approach
2. Add note in "Known Issues" if relevant
3. If significant change, create checkpoint commit

Problem: Multiple blockers, can't proceed

Solution: Use 🚫 status and document

## Phase 5: Payments Integration 🚫
**Blocked**: Need 3 decisions:
1. Stripe vs. PayPal? (user preference)
2. Webhook URL for production? (DevOps team)
3. Test credit card limits? (compliance team)

**Resume When**: All 3 decisions made
**Next Action**: Implement chosen payment provider integration

---

Integration with Tools

With project-planning Skill

1. project-planning creates IMPLEMENTATION_PHASES.md
2. project-session-management creates SESSION.md from phases
3. Work through phases, updating SESSION.md
4. Checkpoints preserve state

With Git

• SESSION.md is committed (part of project state)
• Checkpoint commits use structured format
• git log --grep="checkpoint:" shows milestones
• SESSION.md refers to checkpoint commits

With Claude Code

• SESSION.md is small enough to stay in context
• References planning docs (don't duplicate)
• Concrete "Next Action" enables instant resume
• Works across multiple Claude Code sessions

---

Metrics for Success

Good Session Management

• ✅ Can resume in <1 minute after context clear
• ✅ SESSION.md always current (<1 day stale)
• ✅ Checkpoint commits every 2-4 hours of work
• ✅ Next Action is always concrete
• ✅ Never lost progress on context clear

Needs Improvement

• ⚠️ SESSION.md out of sync (>2 days stale)
• ⚠️ Next Actions are vague
• ⚠️ No checkpoints in last 8 hours of work
• ⚠️ Lost progress on context clear
• ⚠️ Confusion about what to do next

---

Advanced Techniques

Multi-Branch Workflow

For working on multiple features simultaneously:

# Session State

**Current Branch**: feature/auth-refactor
**Current Phase**: Phase 5 (Auth refactor)

## Active Branches

### main (Phase 9 complete)
**Last Checkpoint**: abc123
**Status**: Stable, deployed to production

### feature/auth-refactor (Phase 5 in progress)
**Last Checkpoint**: def456
**Next**: Refactor JWT verification in src/middleware/auth.ts:34

### hotfix/bug-123 (Phase 3 paused)
**Last Checkpoint**: ghi789
**Blocked**: Waiting for API provider fix

Phase Dependencies

When phases have dependencies:

## Phase 7: Notifications 🚫
**Blocked By**: Phase 6 (Email Service Setup) must complete first
**Dependency**: Needs email templates and service configured
**Estimated Start**: After Phase 6 complete (2025-10-25)
**Spec**: `docs/IMPLEMENTATION_PHASES.md#phase-7`

---

Last Updated: 2025-10-28 Version: 1.0 Author: Jeremy Dawes | Jezweb