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:

No argument (default): /track-session

• Automatically save current session progress to SESSION_PROGRESS.md
• Then immediately resume from that progress and continue work
• Use when you want to create a checkpoint and keep working

Save only: /track-session save

• Save current session state to SESSION_PROGRESS.md
• Stop and wait for user to continue
• Use when pausing work or reaching a natural stopping point

Resume only: /track-session resume

• Read existing SESSION_PROGRESS.md
• Load the plan, current status, and failed attempts
• Continue from where work was left off
• Use when starting a new session or returning after a break

Verify only: /track-session verify

• Read SESSION_PROGRESS.md and verify all work against initial requirements
• Check that completed tasks actually meet their goals
• Validate dependencies are satisfied
• Report gaps, incomplete work, or deviations from plan
• Use when work appears complete or before final 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

Workflow by Mode

Mode 1: Save and Resume (Default)

Command: /track-session

Create/update SESSION_PROGRESS.md with current status, then immediately continue work. Use for checkpoints during active work, before risky changes, or at natural breaking points.

Mode 2: Save Only

Command: /track-session save

Save current state to SESSION_PROGRESS.md and stop. Use when ending a work session, pausing work, creating handoff documentation, or before taking a break.

Mode 3: Resume Only

Command: /track-session resume

Read SESSION_PROGRESS.md (error if missing), load plan/status/failed attempts, continue from checkpoint. Use when starting new session after break, recovering from context reset, or taking over work.

Mode 4: Verify Only

Command: /track-session verify

Validate completed tasks against original requirements. Checks: work actually done, requirements met, dependencies satisfied, no scope gaps. Generates report with ✅ verified, ⚠️ minor issues, ❌ blockers, 📋 next steps. Use before declaring done or delivery.

See: Detailed Verification Guide for full methodology.

Rules

1. Never repeat failures – Log every failed approach with reason
2. Resume from checkpoint – Check for existing SESSION_PROGRESS.md at session start
3. Keep current – File should always reflect actual state
4. Be specific – Include enough detail to resume work after context loss
5. Verify before declaring done – Always run /track-session verify before claiming work is complete
6. 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:

1. Check “Failed Attempts” section
2. Verify approach is different
3. Document why this attempt should work
4. 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:

1. Review each flagged item in the verification report
2. Either:
   • Complete the missing work and re-verify, OR
   • Update SESSION_PROGRESS.md if requirements changed
3. 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