Initial commit

skills/implement-feature/references/session-resumption.md

@@ -0,0 +1,131 @@
+# 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