Initial commit
This commit is contained in:
Zhongwei Li
368
references/best-practices.md
Normal file
368
references/best-practices.md
Normal file
@@ -0,0 +1,368 @@
|
||||
# Session Management Best Practices
|
||||
|
||||
**When to use, how to maintain, and common patterns for successful session management**
|
||||
|
||||
---
|
||||
|
||||
## When to Use Session Management
|
||||
|
||||
### ✅ Use SESSION.md When
|
||||
|
||||
- **Multi-phase projects** (3+ phases)
|
||||
- **Complex implementations** (>8 hours total estimated work)
|
||||
- **Frequent context clears** (working across multiple sessions)
|
||||
- **Multiple parallel projects** (need to switch context often)
|
||||
- **Team collaboration** (others need to understand current state)
|
||||
|
||||
### ❌ Skip SESSION.md When
|
||||
|
||||
- **Single-phase project** (<2 hours of work)
|
||||
- **Spike/prototype** (exploratory work, not production)
|
||||
- **Quick fix** (one-off bug fix or small change)
|
||||
- **Fully completed project** (all phases done, no active work)
|
||||
|
||||
---
|
||||
|
||||
## Maintenance Patterns
|
||||
|
||||
### Update Frequency
|
||||
|
||||
**Update SESSION.md when**:
|
||||
- ✅ Completing a task within a phase
|
||||
- ✅ Moving between stages (Implementation → Verification → Debugging)
|
||||
- ✅ Hitting a blocker or pausing work
|
||||
- ✅ Completing a phase
|
||||
- ✅ Context is getting full (need to checkpoint)
|
||||
|
||||
**Don't update SESSION.md for**:
|
||||
- ❌ Every single line of code
|
||||
- ❌ Minor refactoring during implementation
|
||||
- ❌ Fixing typos or formatting
|
||||
- ❌ Temporary debugging experiments
|
||||
|
||||
**Rule of thumb**: Update after "significant progress" (completing a checklist item, moving stages, or ending session)
|
||||
|
||||
---
|
||||
|
||||
## Git Checkpoint Timing
|
||||
|
||||
### When to Create Checkpoints
|
||||
|
||||
**Always checkpoint when**:
|
||||
- ✅ Phase complete (all verification passed)
|
||||
- ✅ Context getting full (>80% of context window)
|
||||
- ✅ Pausing work (end of day, switching projects)
|
||||
- ✅ Hit a blocker (waiting for decision or external input)
|
||||
|
||||
**Consider checkpointing when**:
|
||||
- ⚡ Finishing a major task (e.g., all CRUD endpoints done)
|
||||
- ⚡ Switching stages (Implementation → Verification)
|
||||
- ⚡ After fixing a complex bug
|
||||
|
||||
**Don't checkpoint**:
|
||||
- ❌ Every commit (checkpoints are milestones, not commits)
|
||||
- ❌ Work in progress (wait for completed task)
|
||||
- ❌ Failed experiments (revert instead)
|
||||
|
||||
---
|
||||
|
||||
## Next Action Quality
|
||||
|
||||
### ✅ Good Next Actions (Concrete)
|
||||
|
||||
```markdown
|
||||
**Next Action**: Implement PATCH /api/tasks/:id in src/routes/tasks.ts:47, handle validation and ownership check
|
||||
```
|
||||
- File path: `src/routes/tasks.ts`
|
||||
- Line number: `47`
|
||||
- Specific action: "Implement PATCH endpoint"
|
||||
- Context: "handle validation and ownership check"
|
||||
|
||||
```markdown
|
||||
**Next Action**: Fix validation bug in src/middleware/validate.ts:23, add try-catch for Zod errors
|
||||
```
|
||||
- Debugging-focused
|
||||
- Specific file and line
|
||||
- Clear fix needed
|
||||
|
||||
```markdown
|
||||
**Next Action**: Decide: client-side tag filtering or add SQL query parameter? Then resume at src/routes/tasks.ts:89
|
||||
```
|
||||
- Decision point clearly stated
|
||||
- Resume point provided
|
||||
- User knows this is blocked on their choice
|
||||
|
||||
### ❌ Bad Next Actions (Vague)
|
||||
|
||||
```markdown
|
||||
**Next Action**: Continue working on API
|
||||
```
|
||||
- Which API endpoint?
|
||||
- Which file?
|
||||
- What specifically needs to be done?
|
||||
|
||||
```markdown
|
||||
**Next Action**: Fix bugs
|
||||
```
|
||||
- Which bugs?
|
||||
- Where are they?
|
||||
- No concrete starting point
|
||||
|
||||
```markdown
|
||||
**Next Action**: Finish Phase 3
|
||||
```
|
||||
- What's left to do?
|
||||
- No specific task
|
||||
- No file path
|
||||
|
||||
---
|
||||
|
||||
## Status Icon Usage
|
||||
|
||||
### Phase Status
|
||||
|
||||
- **⏸️ Pending** - Not started yet, waiting for earlier phases
|
||||
- **🔄 In Progress** - Currently working on this phase
|
||||
- **✅ Complete** - All tasks done, verification passed
|
||||
- **🚫 Blocked** - Cannot proceed due to external blocker
|
||||
|
||||
**Rules**:
|
||||
- Only ONE phase should be 🔄 at a time (current focus)
|
||||
- Use 🚫 sparingly (most "blockers" are really pauses)
|
||||
- Mark ✅ only when verification complete (not just code written)
|
||||
|
||||
### Task Status
|
||||
|
||||
Within a phase's progress checklist:
|
||||
- `- [ ]` = Not started
|
||||
- `- [ ]` with `← **CURRENT**` = Working on this now
|
||||
- `- [x]` = Completed
|
||||
- `- [x]` with `✅` = Completed and verified
|
||||
|
||||
---
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Pattern: Mid-Phase Context Clear
|
||||
|
||||
**Scenario**: Implementing Phase 3, context at 85%, still have 3 tasks left
|
||||
|
||||
**Action**:
|
||||
1. Update SESSION.md progress (mark completed tasks with `[x]`)
|
||||
2. Set "Next Action" to next uncompleted task
|
||||
3. Create checkpoint commit (status: In Progress)
|
||||
4. Push to remote
|
||||
5. Clear context
|
||||
6. New session: Read SESSION.md, go to "Next Action"
|
||||
|
||||
**Example SESSION.md update**:
|
||||
```markdown
|
||||
## Phase 3: Tasks API 🔄
|
||||
**Progress**:
|
||||
- [x] GET /api/tasks endpoint (commit: abc123)
|
||||
- [x] POST /api/tasks endpoint (commit: def456)
|
||||
- [ ] PATCH /api/tasks/:id ← **CURRENT**
|
||||
- [ ] DELETE /api/tasks/:id
|
||||
- [ ] Verify all endpoints
|
||||
|
||||
**Next Action**: Implement PATCH /api/tasks/:id in src/routes/tasks.ts:47
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Pattern: Verification Stage Tracking
|
||||
|
||||
**Scenario**: Phase 3 code complete, now verifying against criteria
|
||||
|
||||
**Action**:
|
||||
1. Change "Current Stage" to "Verification"
|
||||
2. Add "Verification Progress" section
|
||||
3. Check off criteria as you test
|
||||
4. Note failures with ❌ and description
|
||||
|
||||
**Example SESSION.md update**:
|
||||
```markdown
|
||||
## Phase 3: Tasks API 🔄
|
||||
**Current Stage**: Verification
|
||||
|
||||
**Verification Progress**:
|
||||
- [x] GET /api/tasks returns 200 ✅
|
||||
- [x] POST /api/tasks creates task ✅
|
||||
- [ ] POST with invalid data returns 400 ❌ (returns 500)
|
||||
- [ ] PATCH updates task
|
||||
- [ ] DELETE removes task
|
||||
|
||||
**Current Issue**: Invalid data returning 500 instead of 400. Need to check validation middleware in src/middleware/validate.ts
|
||||
```
|
||||
|
||||
**Next**: Switch to "Debugging" stage, fix the issue, return to "Verification"
|
||||
|
||||
---
|
||||
|
||||
### Pattern: Phase Complete
|
||||
|
||||
**Scenario**: All verification passed, phase is done
|
||||
|
||||
**Action**:
|
||||
1. Change phase status from 🔄 to ✅
|
||||
2. Add completion date and checkpoint
|
||||
3. Collapse to 2-3 lines
|
||||
4. Change next phase from ⏸️ to 🔄
|
||||
5. Create checkpoint commit (status: Complete)
|
||||
|
||||
**Before**:
|
||||
```markdown
|
||||
## Phase 3: Tasks API 🔄
|
||||
**Progress**:
|
||||
- [x] GET /api/tasks endpoint
|
||||
- [x] POST /api/tasks endpoint
|
||||
- [x] PATCH /api/tasks/:id
|
||||
- [x] DELETE /api/tasks/:id
|
||||
- [x] Verify all endpoints ✅
|
||||
|
||||
**Next Action**: Verify DELETE endpoint
|
||||
```
|
||||
|
||||
**After**:
|
||||
```markdown
|
||||
## Phase 3: Tasks API ✅
|
||||
**Completed**: 2025-10-23 | **Checkpoint**: ghi789
|
||||
**Summary**: All CRUD endpoints implemented and verified
|
||||
|
||||
## Phase 4: Task UI 🔄
|
||||
**Type**: UI | **Started**: 2025-10-23
|
||||
**Spec**: `docs/IMPLEMENTATION_PHASES.md#phase-4`
|
||||
**Next Action**: Create TaskList component in src/components/TaskList.tsx
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Problem: SESSION.md growing too large (>200 lines)
|
||||
|
||||
**Solution**: Archive completed phases
|
||||
1. Create `SESSION_ARCHIVE.md`
|
||||
2. Move completed phases there
|
||||
3. Keep only current + next 2-3 phases in SESSION.md
|
||||
|
||||
### Problem: Forgot to update SESSION.md, now out of sync
|
||||
|
||||
**Solution**: Reconstruct from git history
|
||||
1. Look at recent commits
|
||||
2. Update SESSION.md to match actual state
|
||||
3. Set concrete "Next Action"
|
||||
4. Create checkpoint commit to establish baseline
|
||||
|
||||
### Problem: Next Action is now wrong (changed approach)
|
||||
|
||||
**Solution**: Update immediately
|
||||
1. Change "Next Action" to reflect new approach
|
||||
2. Add note in "Known Issues" if relevant
|
||||
3. If significant change, create checkpoint commit
|
||||
|
||||
### Problem: Multiple blockers, can't proceed
|
||||
|
||||
**Solution**: Use 🚫 status and document
|
||||
```markdown
|
||||
## Phase 5: Payments Integration 🚫
|
||||
**Blocked**: Need 3 decisions:
|
||||
1. Stripe vs. PayPal? (user preference)
|
||||
2. Webhook URL for production? (DevOps team)
|
||||
3. Test credit card limits? (compliance team)
|
||||
|
||||
**Resume When**: All 3 decisions made
|
||||
**Next Action**: Implement chosen payment provider integration
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration with Tools
|
||||
|
||||
### With project-planning Skill
|
||||
|
||||
1. `project-planning` creates IMPLEMENTATION_PHASES.md
|
||||
2. `project-session-management` creates SESSION.md from phases
|
||||
3. Work through phases, updating SESSION.md
|
||||
4. Checkpoints preserve state
|
||||
|
||||
### With Git
|
||||
|
||||
- SESSION.md is committed (part of project state)
|
||||
- Checkpoint commits use structured format
|
||||
- `git log --grep="checkpoint:"` shows milestones
|
||||
- SESSION.md refers to checkpoint commits
|
||||
|
||||
### With Claude Code
|
||||
|
||||
- SESSION.md is small enough to stay in context
|
||||
- References planning docs (don't duplicate)
|
||||
- Concrete "Next Action" enables instant resume
|
||||
- Works across multiple Claude Code sessions
|
||||
|
||||
---
|
||||
|
||||
## Metrics for Success
|
||||
|
||||
### Good Session Management
|
||||
|
||||
- ✅ Can resume in <1 minute after context clear
|
||||
- ✅ SESSION.md always current (<1 day stale)
|
||||
- ✅ Checkpoint commits every 2-4 hours of work
|
||||
- ✅ Next Action is always concrete
|
||||
- ✅ Never lost progress on context clear
|
||||
|
||||
### Needs Improvement
|
||||
|
||||
- ⚠️ SESSION.md out of sync (>2 days stale)
|
||||
- ⚠️ Next Actions are vague
|
||||
- ⚠️ No checkpoints in last 8 hours of work
|
||||
- ⚠️ Lost progress on context clear
|
||||
- ⚠️ Confusion about what to do next
|
||||
|
||||
---
|
||||
|
||||
## Advanced Techniques
|
||||
|
||||
### Multi-Branch Workflow
|
||||
|
||||
For working on multiple features simultaneously:
|
||||
|
||||
```markdown
|
||||
# Session State
|
||||
|
||||
**Current Branch**: feature/auth-refactor
|
||||
**Current Phase**: Phase 5 (Auth refactor)
|
||||
|
||||
## Active Branches
|
||||
|
||||
### main (Phase 9 complete)
|
||||
**Last Checkpoint**: abc123
|
||||
**Status**: Stable, deployed to production
|
||||
|
||||
### feature/auth-refactor (Phase 5 in progress)
|
||||
**Last Checkpoint**: def456
|
||||
**Next**: Refactor JWT verification in src/middleware/auth.ts:34
|
||||
|
||||
### hotfix/bug-123 (Phase 3 paused)
|
||||
**Last Checkpoint**: ghi789
|
||||
**Blocked**: Waiting for API provider fix
|
||||
```
|
||||
|
||||
### Phase Dependencies
|
||||
|
||||
When phases have dependencies:
|
||||
|
||||
```markdown
|
||||
## Phase 7: Notifications 🚫
|
||||
**Blocked By**: Phase 6 (Email Service Setup) must complete first
|
||||
**Dependency**: Needs email templates and service configured
|
||||
**Estimated Start**: After Phase 6 complete (2025-10-25)
|
||||
**Spec**: `docs/IMPLEMENTATION_PHASES.md#phase-7`
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: 2025-10-28
|
||||
**Version**: 1.0
|
||||
**Author**: Jeremy Dawes | Jezweb
|
||||
Reference in New Issue
Block a user