132 lines
3.8 KiB
Markdown
132 lines
3.8 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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
|