3.8 KiB
Session Resumption
Objective
Resume interrupted sessions by detecting completed phases and loading context.
Why This Exists
Users may need to pause and resume feature work. File existence indicates phase completion, enabling precise resumption point detection.
Resumption Detection Protocol
1. Detect resumption request
User provides session slug without "implement" verb:
- ✓ "Continue session-resumption"
- ✓ "Resume auth-flow"
- ✗ "Implement user-login" (fresh start)
2. Locate matching sessions
find docs/sessions -type d -name "*-<slug>" | sort -r
Multiple matches → Ask user which to use (show timestamps).
3. Map file existence to completed phases
Check session directory for phase files:
| File exists | Phase completed | Resume at |
|---|---|---|
| None | Nothing | Phase 1 (fresh start) |
| REQUIREMENTS.md | Phase 1 | Phase 2 (PLAN) |
| PLAN.md | Phase 2 | Phase 3 (IMPLEMENT) |
| IMPLEMENTATION.md | Phase 3 | Infer: Phase 4 or 5 |
| TESTING.md | Phase 5 | Infer: Phase 6 or 7 |
| REFLECTION.md | Phase 7 | Session complete |
Progressive disclosure: Files created when entering each phase, not at initialization.
Phase 4 and 6 inference: These phases (REVIEW, DOCUMENT) don't create files. When ambiguous:
- If IMPLEMENTATION.md exists but TESTING.md doesn't → Ask user: "Resume at Phase 4 (REVIEW) or Phase 5 (VERIFY)?"
- If TESTING.md exists but REFLECTION.md doesn't → Ask user: "Resume at Phase 6 (DOCUMENT) or Phase 7 (REFLECT)?"
4. Load context from existing files
Read ALL existing phase files in session directory:
- REQUIREMENTS.md → requirements, constraints, success criteria
- PLAN.md → implementation approach, files to modify, architectural decisions
- IMPLEMENTATION.md → what was implemented, how it works
- TESTING.md → test strategy, verification results
- REFLECTION.md → learnings, corrections
5. Present resumption summary to user
Example 1: Clear resumption point
"Found session: docs/sessions/20251020-2342-session-resumption
Completed phases:
✓ Phase 1: GATHER REQUIREMENTS
✓ Phase 2: PLAN
Context loaded:
- Requirements: Session resumption with progressive disclosure
- Plan: File-based phase detection using existence markers
Next: Phase 3 (IMPLEMENT)
Proceed with Phase 3?"
Example 2: Ambiguous resumption point (requires user clarification)
"Found session: docs/sessions/20251020-2342-add-metrics
Completed phases:
✓ Phase 1: GATHER REQUIREMENTS
✓ Phase 2: PLAN
✓ Phase 3: IMPLEMENT
Context loaded:
- Requirements: Add usage metrics tracking and export
- Plan: Create metrics collection system with CSV/JSON export
- Implementation: Metrics service and export handlers created
IMPLEMENTATION.md exists but TESTING.md does not.
Resume at Phase 4 (REVIEW) or Phase 5 (VERIFY)?"
6. Resume at next phase
Load appropriate phase reference and continue workflow.
Multiple Session Handling
When multiple sessions match slug:
"Multiple sessions found for 'session-resumption':
1. docs/sessions/20251020-2342-session-resumption (Oct 20, 11:42pm)
- Last phase: IMPLEMENT
2. docs/sessions/20251019-1056-session-resumption (Oct 19, 10:56am)
- Last phase: PLAN
Which session should I resume?"
Wait for user selection.
Critical Anti-Patterns
❌ "Resuming without reading context"
Always read ALL existing phase files. Context is critical for continuity.
❌ "Assuming IMPLEMENTATION.md means implementation is done"
IMPLEMENTATION.md created at end of Phase 3 (before REVIEW). Phase 3 complete, but Phase 4 still needed.
Key Takeaways
- File existence = phase completion marker
- Progressive disclosure prevents false positives
- Always load complete context before resuming
- Multiple matches require user selection