Session Progress

🔄 Session tracking activated - I'll use SESSION_PROGRESS.md to track our work so we can pause and resume anytime.

Overview

Use SESSION_PROGRESS.md in the project root to track plans and progress. All planned work should be saved to SESSION_PROGRESS.md and updated over time. If the plan changes, update SESSION_PROGRESS.

Core principle: Maintain recoverable state so work can pause and resume without losing context.

Usage Modes

This skill supports four modes via optional arguments:

Mode	Command	What it does	Use when
Default	`/track-session`	Save progress, then continue working	Checkpoint during active work
Save	`/track-session save`	Save progress and stop	Pausing work or taking a break
Resume	`/track-session resume`	Load SESSION_PROGRESS.md and continue	Starting new session after break
Verify	`/track-session verify`	Validate completed work against requirements	Before declaring done or delivery

When to Use

Always use when:

Working on multi-phase implementations
Planning complex refactoring across multiple files
Pairing with user on design decisions
Tasks that might span multiple sessions or context resets
Long-running debugging sessions with multiple approaches

Useful for:

Feature development with dependencies between tasks
Large refactoring projects
Learning new codebases with exploration notes
Collaborative work sessions with progress tracking

Avoid when:

Quick 1-2 file changes
Simple bug fixes with obvious solutions
Read-only exploration without planned changes
Tasks that complete in under 5 minutes

When to Update

Update after:

Completing any checklist item
Any change in plan
Any error or failed attempt
Every 2-3 file modifications
Before asking user questions

When to Verify

Run verification:

Before declaring work complete
After all planned tasks are checked off
Before final delivery or handoff
When returning to work after a long break (verify nothing regressed)
After major refactoring (verify functionality preserved)
When user asks "are we done?" or "did we finish everything?"

Format

# Session Progress

## Plan
- [ ] Task 1: Description [dependency: none]
- [x] Task 2: Description [dependency: Task 1]
- [ ] Task 3: Description [dependency: Task 2]

## Current Status
Last updated: [timestamp]
Working on: [current task]
Next: [immediate next step]

## Failed Attempts
- Tried [approach]: Failed because [reason], trying [alternative] instead

## Completed Work
- [timestamp] Task 2: [brief summary of what was done]

## Verification Results
(Added by /track-session verify command)

### ✅ Successfully Verified
- Task/Phase: Evidence of completion and correctness

### ⚠️ Minor Issues Found
- Issue: Description and impact

### ❌ Blocking Issues
- Critical problem: What's broken and why it blocks delivery

### 📋 Recommended Next Steps
1. Specific action to address issues
2. Next action after that

Verification

Command: /track-session verify

Validates completed tasks against original requirements. Checks that work is actually done, requirements met, dependencies satisfied, no scope gaps. Generates report with verified items, minor issues, blockers, and next steps.

See: Detailed Verification Guide for full methodology.

Rules

Never repeat failures - Log every failed approach with reason
Resume from checkpoint - Check for existing SESSION_PROGRESS.md at session start
Keep current - File should always reflect actual state
Be specific - Include enough detail to resume work after context loss
Verify before declaring done - Always run /track-session verify before claiming work is complete
Verification is not optional - Checked boxes don't mean work meets requirements; verification does

Examples

Example: Mode Selection

Scenario 2: Taking a lunch break

user: "Save my progress, I'll be back in an hour" assistant: "/track-session save"

Saves current state and stops

Scenario 3: Coming back from break

user: "I'm back, let's continue" assistant: "/track-session resume"

Reads SESSION_PROGRESS.md and continues from checkpoint

Scenario 4: Creating checkpoint mid-work

assistant: "Completed Phase 2, creating checkpoint before Phase 3" assistant: "/track-session"

Updates SESSION_PROGRESS.md with Phase 2 completion, continues to Phase 3

Scenario 5: Verifying work is complete

user: "Are we done? Did we complete everything?" assistant: "/track-session verify"

Reads SESSION_PROGRESS.md, checks all completed tasks against requirements

Reports: "✅ Phases 1-3 verified. ⚠️ Phase 4 tests not run. Recommend: Run test suite"

Scenario 6: End of work session verification

assistant: "All tasks appear complete. Let me verify before we finish." assistant: "/track-session verify"

Validates all work, generates verification report


**Why this is good:** Clear separation of concerns - save for pausing, resume for continuing, no-arg for checkpointing during active work, verify for validation before delivery.
</Good>

<Bad>
```bash
# Always using save even when you want to continue
user: "Let's build authentication"
assistant: "/track-session save"
# Saves and STOPS, now user has to manually ask to resume

# Using resume without a saved session
user: "Start working on the feature"
assistant: "/track-session resume"
# ERROR: No SESSION_PROGRESS.md exists yet

# Marking tasks complete without verification
assistant: "All tasks are checked off, we're done!"
# Never ran verify to confirm work actually meets requirements

Why this is bad: Using save when you want to continue wastes time. Using resume without prior save fails. Skipping verify means potentially incomplete or incorrect work. Use no-arg mode to save+continue, and always verify before declaring completion.

Example 1: Complex Feature Implementation

Plan

Phase 1: Research authentication libraries [dependency: none]
- Evaluated OAuth.js, Passport.js, Auth0
- Chose Passport.js for flexibility
Phase 2: Set up OAuth flow [dependency: Phase 1]
- Configured Google OAuth provider
- Added callback routes
Phase 3: Add user session management [dependency: Phase 2]
- Implement Redis session store
- Add session cleanup job
Phase 4: Test authentication flows [dependency: Phase 3]
- Test login/logout
- Test session persistence

Current Status

Working on: Phase 3 - Implementing Redis session storage Next: Add Redis client configuration, then implement session middleware

Failed Attempts

Tried in-memory sessions: Failed because sessions not persistent across server restarts, switching to Redis instead
Attempted express-session default store: Performance issues with concurrent users, Redis solves this

Completed Work

Phase 2 completed - OAuth flow working with Google provider
Phase 1 completed - Selected Passport.js after comparing 3 libraries


**Why this is good:** Specific tasks with clear dependencies, documented decisions, failed attempts recorded with reasons, concrete next steps.
</Good>

<Bad>
```markdown
# Session Progress

## Plan
- [ ] Do auth stuff
- [ ] Fix sessions
- [ ] Test it

Working on auth. Tried some things that didn't work.

Why this is bad: Too vague, no dependencies tracked, no details on what failed or why, impossible to resume without starting over.

Example 2: Debugging Session

Plan

Phase 1: Reproduce bug [dependency: none]
Phase 2: Identify root cause [dependency: Phase 1]
Phase 3: Implement fix [dependency: Phase 2]
Phase 4: Verify fix with tests [dependency: Phase 3]

Current Status

Working on: Phase 3 - Implementing race condition fix Next: Add mutex lock around shared resource access in payment processor

Failed Attempts

Checked payment API logs: No errors found, bug is client-side
Added try-catch around payment call: Still crashes, race condition suspected
Increased timeout values: Made it worse, confirms race condition hypothesis

Completed Work

Phase 2 - Root cause identified: race condition in payment state management
Phase 1 - Bug reproduced consistently with concurrent payment attempts


**Why this is good:** Clear progression through debugging phases, failed attempts inform next steps, root cause documented.
</Good>

<Bad>
```markdown
# Session Progress

Debugging payment bug. Tried a few things. Need to fix it.

Why this is bad: No systematic approach, no record of what was tried, no hypothesis tracking.

Example 3: Verification Workflow

Plan

Phase 1: Set up authentication system
Phase 2: Implement user registration
Phase 3: Add email verification
Phase 4: Write tests

Verification Results

✅ All phases verified with passing tests (23/23) ⚠️ Minor: Email template styling, no rate limiting 📋 Next: Add rate limiting, customize templates


**Why this is good:** Verification report shows evidence (test counts, specific issues), separates critical vs. nice-to-have, provides actionable next steps.
</Good>

<Bad>
```markdown
## Plan
- [x] Phase 1: Authentication
- [x] Phase 2: Registration
- [x] Phase 3: Email stuff
- [x] Phase 4: Tests

Everything is done! ✨

Why this is bad: No verification performed, no evidence work meets requirements, potentially incomplete work.

Troubleshooting

Problem: SESSION_PROGRESS.md getting too large (>1000 lines)

Cause: Not archiving completed work periodically.

Solution:

# Archive completed phases to separate file
cat SESSION_PROGRESS.md >> SESSION_ARCHIVE_2025-01.md
# Keep only active phases in SESSION_PROGRESS.md

Move completed work to archive file monthly or after major milestones.

Problem: Lost track of what was being worked on

Cause: Didn't update "Current Status" before pausing session.

Solution:

Update SESSION_PROGRESS.md before asking user questions
Update before context resets
Update every 2-3 file modifications
Set reminder: "Last updated" timestamp should be recent

Problem: Can't resume work after long break

Cause: Not enough detail in "Next" field.

Solution: Include specific next action with file and function names:

Next: Add mutex lock in src/payment/processor.ts:handlePayment()
around lines 45-60 where paymentState is accessed

Not just: "Next: Fix the bug"

Problem: Repeated failed attempts with same approach

Cause: Not reading or updating "Failed Attempts" section.

Solution: Before trying new approach:

Check "Failed Attempts" section
Verify approach is different
Document why this attempt should work
Add failed attempt immediately when it fails

Problem: Resume fails with "No SESSION_PROGRESS.md found"

Cause: Trying to resume without first saving a session.

Solution:

Use /track-session (no argument) to create initial session
Or use /track-session save to create SESSION_PROGRESS.md first
Resume only works when SESSION_PROGRESS.md already exists

Problem: Save mode stops work when you wanted to continue

Cause: Using save argument instead of no argument.

Solution:

Use /track-session save ONLY when pausing work
Use /track-session (no arg) to checkpoint and continue
Default no-arg mode is for active work with checkpoints

Problem: Unclear which mode to use

Cause: Not understanding the difference between modes.

Solution: Quick decision guide:

Continuing work? Use no argument (default)
Stopping for a break? Use save
Coming back to work? Use resume
Think you're done? Use verify

Problem: Verify reports work incomplete but all tasks are checked

Cause: Tasks were marked complete without actually finishing the work, or requirements changed.

Solution:

Review each flagged item in the verification report
Either:
- Complete the missing work and re-verify, OR
- Update SESSION_PROGRESS.md if requirements changed
Never skip verification - checked boxes don't mean work is actually done

Problem: Verify mode takes too long

Cause: Too many completed tasks to verify at once.

Solution:

Run verify incrementally after each major phase
Don't wait until the end to verify everything
Use /track-session verify after completing each group of related tasks
Archive verified phases to SESSION_ARCHIVE.md to reduce scope

Problem: Verify passes but work still has bugs

Cause: Verification wasn't thorough enough (didn't run tests, check edge cases, etc.)

Solution: Verification should include:

Running test suites (unit, integration, e2e)
Manual testing of key user flows
Checking error handling and edge cases
Validating against original acceptance criteria
Code review of critical changes

Integration

This skill works with:

git-worktree - Each worktree should have its own SESSION_PROGRESS.md for parallel work tracking
All methodology skills - Track phase completion for TDD, debugging, code review workflows
generate-skill - Use SESSION_PROGRESS.md to track multi-phase skill creation
Long-running tasks - Any task requiring >15 minutes or multiple context resets

Integration pattern with git-worktree:

# Create worktree for feature
git worktree add ../project-feature feature-branch
cd ../project-feature

# Create separate progress tracking
echo "# Session Progress - Feature Branch" > SESSION_PROGRESS.md
# Work on feature with independent progress tracking

Pairs with:

Commit workflows - Track progress between commits
Testing workflows - Track test implementation phases
Refactoring - Track refactoring phases and rollback points