Session Management Guide

Phase Tracking

Sessions track EDIRD phases:

• NOTES.md: "Current Phase" section with phase, last verb, gate status
• PROGRESS.md: "Phase Plan" section with 5 phases and status

MUST-NOT-FORGET

• Session folder location: [DEFAULT_SESSIONS_FOLDER]/_YYYY-MM-DD_[SessionTopicCamelCase]/
• Default: [DEFAULT_SESSIONS_FOLDER] = [WORKSPACE_FOLDER] (override in !NOTES.md)
• Required files: NOTES.md, PROBLEMS.md, PROGRESS.md
• Lifecycle: Init → Work → Save → Resume → Finalize → Archive
• Sync session PROBLEMS.md to project on /session-finalize
• Phase tracking: NOTES.md has current phase, PROGRESS.md has full phase plan
• STOP after session init: After creating session files, STOP and wait for user review. Do NOT implement session goal until explicitly requested. User must review and refine goals before work begins.

Session Lifecycle

1. Init (/session-new): Create session folder with tracking files
2. Work: Create specs, plans, implement, track progress
3. Save (/session-save): Document findings, commit changes
4. Resume (/session-load): Re-read session documents, continue work
5. Finalize (/session-finalize): Sync findings to project files, prepare for archive

Session Folder Location

Base: [DEFAULT_SESSIONS_FOLDER] (default: [WORKSPACE_FOLDER], can be overridden in !NOTES.md)

Format: [DEFAULT_SESSIONS_FOLDER]/_YYYY-MM-DD_[SessionTopicCamelCase]/

Example: _PrivateSessions/_2026-01-12_FixAuthenticationBug/

Required Session Files

Use templates from this skill folder:

• NOTES.md (NOTES_TEMPLATE.md): Key information, agent instructions, working patterns, large initial prompts (>120 tokens)
• PROBLEMS.md (PROBLEMS_TEMPLATE.md): All problems to be addressed - initial prompts, questions, feature requests, bugs, strange behavior, investigation topics. Each problem gets a unique ID and tracks status (Open/Resolved/Deferred)
• PROGRESS.md (PROGRESS_TEMPLATE.md): Task execution tracking - to-do list, done items, tried-but-not-used approaches

Key distinction:

• NOTES.md = Context and reference information (static knowledge)
• PROBLEMS.md = All topics requiring attention (dynamic problem list with IDs)
• PROGRESS.md = Task execution status (what's being worked on)

Assumed Workflow

1. INIT: User initializes session (`/session-new`)
   └── Session folder, NOTES.md, PROBLEMS.md, PROGRESS.md created

2. PREPARE (one of):
   A) User prepares work manually
      └── Creates INFO / SPEC / IMPL documents, tracks progress
   B) User explains problem, agent assists
      └── Updates Problems, Progress, Notes → researches → creates documents

3. WORK: User or agent implements
   └── Makes decisions, creates tests, implements, verifies
   └── Progress and findings tracked continuously

4. SAVE: User saves session for later (`/session-save`)
   └── Everything updated and committed

5. RESUME: User resumes session (`/session-load`)
   └── Agent primes from session files, executes workflows in Notes
   └── Continue with steps 2-3

6. FINALIZE: User finalizes session (`/session-finalize`)
   └── Everything updated, committed, synced to project/workspace

7. ARCHIVE: User archives session
   └── Session folder moved to _Archive/

ID System

See [AGENT_FOLDER]/rules/devsystem-ids.md rule (always-on) for complete ID system.

Quick Reference:

• Document: [TOPIC]-[DOC][NN] (IN, SP, IP, TP)
  • Example: CRWL-SP01, AUTH-IP01
• Tracking: [TOPIC]-[TYPE]-[NNN] (BG = Bug, FT = Feature, PR = Problem, FX = Fix, TK = Task)
  • Example: SAP-BG-001, UI-PR-003, GLOB-TK-015
• Topic Registry: Maintained in project NOTES.md

Session Init Template

NOTES.md

# Session Notes

## Session Info
- **Started**: [DATE]
- **Goal**: [Brief description]

## Key Decisions

## Important Findings

## Workflows to Run on Resume

PROBLEMS.md

# Session Problems

## Open

## Resolved

## Deferred

PROGRESS.md

# Session Progress

## To Do

## In Progress

## Done

## Tried But Not Used