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
Resume	/track-session resume	Load SESSION_PROGRESS.md and continue	Returning to a project, picking up where you left off
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
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

---
schema: cc-dash/session@1
project: project-name-here
session_id: s_YYYY-MM-DD_topic-slug
roadmap_ref: r_XXXXX
started: YYYY-MM-DDTHH:MM:SS-TZ
last_updated: YYYY-MM-DDTHH:MM:SS-TZ
status: in-progress
---

# Session Progress

## Plan

- [ ] <!-- id:t_XXXXX dep:none --> Task 1: Description
- [x] <!-- id:t_XXXXX dep:t_XXXXX --> Task 2: Description
- [ ] <!-- id:t_XXXXX dep:t_XXXXX --> Task 3: Description

## Current Status

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

## Decisions

- [decision description]

## Failed Attempts

- <!-- id:f_XXXXX task:t_XXXXX --> Tried [approach]: Failed because [reason], trying [alternative] instead

## Completed Work

- <!-- ref:t_XXXXX at:YYYY-MM-DDTHH:MM:SS-TZ --> 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

Format Rules

1. Frontmatter is required - Must include schema, project, session_id, started, last_updated, status
2. Every plan item gets an ID - Format: t_ + 5 random alphanumeric characters
3. Every plan item declares dependencies - dep:t_XXXXX or dep:none
4. roadmap_ref links to the roadmap - Set when session implements a specific roadmap feature
5. Checkboxes are the primary status - [ ] = not done, [x] = done
6. Failed attempts reference tasks - task:t_XXXXX links the failure to what was being attempted
7. Completed work references tasks - ref:t_XXXXX at:timestamp for traceability
8. Session status in frontmatter - in-progress, paused, completed, or blocked

ID Generation

Generate IDs using 5 random characters from [a-z0-9]. Prefixes:

• t_ = task (plan items)
• f_ = failed attempt
• s_ = session (in session_id, uses date + slug instead of random)

Migration from v1

If you encounter a SESSION_PROGRESS.md without frontmatter or IDs, see the Migration Guide for step-by-step instructions on upgrading to v2 format.

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

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

Session Progress

Plan

• Phase 1: Research authentication libraries
  • Evaluated OAuth.js, Passport.js, Auth0
  • Chose Passport.js for flexibility
• Phase 2: Set up OAuth flow
  • Configured Google OAuth provider
  • Added callback routes
• Phase 3: Add user session management
  • Implement Redis session store
  • Add session cleanup job
• Phase 4: Test authentication flows
  • 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

Completed Work

**Why this is good:** Frontmatter with schema and session metadata, specific tasks with IDs and explicit dependencies, failed attempts linked to tasks, completed work with timestamps and task references, 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

Session Progress

Plan

• Phase 1: Reproduce bug
• Phase 2: Identify root cause
• Phase 3: Implement fix
• Phase 4: Verify fix with tests

Current Status

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

Failed Attempts

Completed Work

**Why this is good:** Clear progression through debugging phases, failed attempts linked to tasks with IDs, root cause documented, frontmatter tracks session metadata.
</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

Session Progress

Plan

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

Verification Results

Successfully Verified

• All phases verified with passing tests (23/23)

Minor Issues Found

• Email template styling needs polish, no rate limiting on registration endpoint

Blocking Issues

• None

**Why this is good:** Verification report uses plain headings (no emojis), shows evidence (test counts, specific issues), separates critical vs. nice-to-have, frontmatter shows session is completed.
</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.

Quality Signals

A well-tracked session has these properties:

• Frontmatter has schema, project, session_id, and timestamps — machine-parseable for dashboard ingestion
• Every task has an ID and explicit dependency — dep:none or dep:t_XXXXX, never omitted
• "Current Status" reflects actual state — updated within the last 2-3 file modifications
• Failed attempts reference the task they belong to — with a clear reason why it failed
• "Next" field names specific files and functions — not just "fix the bug"
• Completed work has timestamps — ref:t_XXXXX at:timestamp for traceability

Troubleshooting

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: 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: 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

Extended Troubleshooting — File size management, repeated failures, verify edge cases, and more.

Integration

This skill works with:

• track-roadmap - Pick a feature from the roadmap, then use track-session to plan and track its implementation
• 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

Pairs with:

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