Initial commit
This commit is contained in:
Zhongwei Li
538
commands/story-timebox.md
Normal file
538
commands/story-timebox.md
Normal file
@@ -0,0 +1,538 @@
|
||||
# /sdd:story-timebox
|
||||
|
||||
## Meta
|
||||
- Version: 2.0
|
||||
- Category: productivity
|
||||
- Complexity: medium
|
||||
- Purpose: Set focused work session timer with progress tracking and checkpoints
|
||||
|
||||
## Definition
|
||||
**Purpose**: Start a time-boxed work session with automatic progress checkpoints, metrics tracking, and session logging for story development.
|
||||
|
||||
**Syntax**: `/sdd:story-timebox [duration] [mode]`
|
||||
|
||||
## Parameters
|
||||
| Parameter | Type | Required | Default | Description | Validation |
|
||||
|-----------|------|----------|---------|-------------|------------|
|
||||
| duration | number | No | 2 | Session duration in hours | 0.5-8 hours |
|
||||
| mode | string | No | standard | Timer mode: standard or pomodoro | standard/pomodoro |
|
||||
|
||||
## INSTRUCTION: Start Timeboxed Work Session
|
||||
|
||||
### INPUTS
|
||||
- duration: Session length in hours (or use default)
|
||||
- mode: Timer mode (standard with checkpoints or pomodoro technique)
|
||||
- Current active story from `/docs/stories/development/`
|
||||
- Session goal from user
|
||||
|
||||
### PROCESS
|
||||
|
||||
#### Phase 1: Session Initialization
|
||||
1. **DETERMINE** session parameters:
|
||||
- IF duration provided: USE specified hours
|
||||
- IF no duration: DEFAULT to 2 hours
|
||||
- IF mode provided: USE specified mode (standard/pomodoro)
|
||||
- IF no mode: DEFAULT to standard
|
||||
|
||||
2. **FIND** active story:
|
||||
- SCAN `/docs/stories/development/` for active story
|
||||
- IF multiple stories: ASK user which story to focus on
|
||||
- IF no active story: SUGGEST using `/sdd:story-start [id]` first
|
||||
|
||||
3. **ASK** user for session goal:
|
||||
- "What do you want to accomplish in this session?"
|
||||
- RECORD goal for tracking
|
||||
|
||||
#### Phase 2: Session Planning
|
||||
1. **CALCULATE** time checkpoints:
|
||||
|
||||
IF standard mode (duration in hours):
|
||||
- Start time: [current timestamp]
|
||||
- 25% checkpoint: [start + 0.25 * duration]
|
||||
- 50% checkpoint: [start + 0.50 * duration]
|
||||
- 75% checkpoint: [start + 0.75 * duration]
|
||||
- End time: [start + duration]
|
||||
|
||||
IF pomodoro mode:
|
||||
- Calculate 25-minute work intervals
|
||||
- 5-minute short breaks
|
||||
- 15-minute long break after 4 intervals
|
||||
- Total time based on duration
|
||||
|
||||
2. **GENERATE** session plan based on goal:
|
||||
- Break down goal into 4 quarterly segments
|
||||
- Suggest specific tasks for each quarter
|
||||
- Include testing and cleanup phases
|
||||
|
||||
3. **CREATE** session tracking file:
|
||||
- Location: `.timebox/session-[timestamp].md`
|
||||
- Contains: Story ID, goal, plan, checkpoints
|
||||
|
||||
#### Phase 3: Session Start Display
|
||||
1. **DISPLAY** session start summary:
|
||||
```
|
||||
⏰ TIMEBOX SESSION STARTED
|
||||
═══════════════════════════════════
|
||||
|
||||
Duration: [X] hours ([X] minutes)
|
||||
Started: [HH:MM AM/PM]
|
||||
Ends at: [HH:MM AM/PM]
|
||||
|
||||
Story: [STORY-ID] - [Title]
|
||||
Session Goal: [User's stated goal]
|
||||
|
||||
📍 CHECKPOINTS:
|
||||
- 25% ([HH:MM]): Quick progress check
|
||||
- 50% ([HH:MM]): Halfway review
|
||||
- 75% ([HH:MM]): Wrap-up warning
|
||||
- 100% ([HH:MM]): Session complete
|
||||
|
||||
Timer Mode: [Standard/Pomodoro]
|
||||
```
|
||||
|
||||
2. **SHOW** session plan:
|
||||
```
|
||||
📋 SESSION PLAN
|
||||
══════════════════════════════════
|
||||
|
||||
Quarter 1 (0-25%): [Focus area]
|
||||
- [ ] [Specific task 1]
|
||||
- [ ] [Specific task 2]
|
||||
|
||||
Quarter 2 (25-50%): [Focus area]
|
||||
- [ ] [Specific task 3]
|
||||
- [ ] [Specific task 4]
|
||||
|
||||
Quarter 3 (50-75%): [Focus area]
|
||||
- [ ] [Test what was built]
|
||||
- [ ] [Address any issues found]
|
||||
|
||||
Quarter 4 (75-100%): [Focus area]
|
||||
- [ ] [Commit changes]
|
||||
- [ ] [Update story progress]
|
||||
- [ ] [Document session notes]
|
||||
|
||||
🎯 START NOW: Begin with [first task]
|
||||
```
|
||||
|
||||
3. **REMIND** user:
|
||||
- I'll check in at each checkpoint
|
||||
- Mention checkpoints when user provides updates
|
||||
- Track progress throughout session
|
||||
|
||||
#### Phase 4: Checkpoint Management
|
||||
**At each 25%, 50%, 75% checkpoint**, IF user interacts:
|
||||
|
||||
1. **DISPLAY** checkpoint notification:
|
||||
```
|
||||
🔔 CHECKPOINT: [25/50/75]% Complete
|
||||
═══════════════════════════════════
|
||||
|
||||
Time Elapsed: [X] minutes
|
||||
Time Remaining: [X] minutes
|
||||
Current Time: [HH:MM AM/PM]
|
||||
|
||||
Progress Check:
|
||||
- Planned: [Tasks planned for this quarter]
|
||||
- What's done: [Ask user what was completed]
|
||||
- On track: [Calculate based on response]
|
||||
|
||||
[IF on track:]
|
||||
Great progress! Continue with: [next planned task]
|
||||
|
||||
[IF behind:]
|
||||
Adjust plan: [Suggest focusing on priority items]
|
||||
|
||||
[IF ahead:]
|
||||
Excellent! Consider: [Suggest stretch goals]
|
||||
```
|
||||
|
||||
2. **UPDATE** session tracking file:
|
||||
- Log checkpoint reached
|
||||
- Record user's progress update
|
||||
- Note any plan adjustments
|
||||
|
||||
#### Phase 5: Session Metrics Tracking
|
||||
**Throughout session**, TRACK:
|
||||
|
||||
1. **Code Metrics** (if user commits/shows changes):
|
||||
- Lines added/removed
|
||||
- Files modified
|
||||
- Commits made
|
||||
|
||||
2. **Test Metrics** (if tests run):
|
||||
- Tests added
|
||||
- Tests passing/failing
|
||||
- Coverage changes
|
||||
|
||||
3. **Progress Metrics**:
|
||||
- Tasks completed vs planned
|
||||
- Checkpoint adherence
|
||||
- Goal achievement percentage
|
||||
|
||||
#### Phase 6: Session Interruption Handling
|
||||
IF user says "pause", "stop", "brb", or similar:
|
||||
|
||||
1. **PAUSE** session:
|
||||
```
|
||||
⏸️ SESSION PAUSED
|
||||
═══════════════════════════════════
|
||||
|
||||
Paused at: [HH:MM AM/PM]
|
||||
Time Elapsed: [X] minutes
|
||||
Time Remaining: [X] minutes
|
||||
|
||||
Progress so far:
|
||||
- [Tasks completed]
|
||||
|
||||
To resume: Simply mention you're back or say "resume"
|
||||
To end early: Say "end session"
|
||||
```
|
||||
|
||||
2. **SAVE** pause state to session tracking file
|
||||
|
||||
IF user returns:
|
||||
1. **RESUME** session:
|
||||
```
|
||||
▶️ SESSION RESUMED
|
||||
═══════════════════════════════════
|
||||
|
||||
Welcome back!
|
||||
Time Remaining: [X] minutes
|
||||
Next Checkpoint: [time]
|
||||
|
||||
Continue with: [current task]
|
||||
```
|
||||
|
||||
#### Phase 7: Session Completion
|
||||
**At session end** OR IF user says "end session":
|
||||
|
||||
1. **DISPLAY** session summary:
|
||||
```
|
||||
✅ SESSION COMPLETE
|
||||
═══════════════════════════════════
|
||||
|
||||
Total Duration: [X] hours [X] minutes
|
||||
Story: [STORY-ID] - [Title]
|
||||
|
||||
SESSION GOAL:
|
||||
[Original goal stated]
|
||||
|
||||
ACCOMPLISHED:
|
||||
✓ [Completed task 1]
|
||||
✓ [Completed task 2]
|
||||
✓ [Completed task 3]
|
||||
⏳ [Partial task - note what's left]
|
||||
|
||||
SESSION METRICS:
|
||||
- Planned vs Actual: [X]%
|
||||
- Code changes: [X] files, [X] lines
|
||||
- Commits: [X]
|
||||
- Tests: [X] added, [X/Y] passing
|
||||
- Checkpoints hit: [X/4]
|
||||
|
||||
WHAT WENT WELL:
|
||||
- [Success point 1]
|
||||
- [Success point 2]
|
||||
|
||||
CHALLENGES:
|
||||
- [Challenge encountered]
|
||||
- [How addressed or needs addressing]
|
||||
|
||||
FOR NEXT SESSION:
|
||||
- [Specific next task to start with]
|
||||
- [Any blockers to resolve first]
|
||||
- [Estimated time needed]
|
||||
|
||||
NEXT STEPS:
|
||||
1. /sdd:story-save # Save progress to story
|
||||
2. /sdd:story-quick-check # Verify everything works
|
||||
3. Take a break! 🎉
|
||||
```
|
||||
|
||||
2. **ASK** user for session notes:
|
||||
- "What went well this session?"
|
||||
- "What was challenging?"
|
||||
- "What should you focus on next time?"
|
||||
|
||||
3. **UPDATE** story progress log:
|
||||
- Append session summary to story file
|
||||
- Note tasks completed and time spent
|
||||
- Record any blockers or notes
|
||||
|
||||
4. **SAVE** session to history:
|
||||
- Complete session tracking file
|
||||
- Add to `.timebox/history/` for velocity analysis
|
||||
|
||||
5. **SUGGEST** next session:
|
||||
- Based on progress rate
|
||||
- Consider remaining work
|
||||
- Recommend duration and focus
|
||||
|
||||
#### Phase 8: Pomodoro Mode (Special Handling)
|
||||
IF mode = pomodoro:
|
||||
|
||||
1. **STRUCTURE** session as intervals:
|
||||
```
|
||||
🍅 POMODORO MODE ACTIVE
|
||||
═══════════════════════════════════
|
||||
|
||||
Session Structure:
|
||||
🍅 Pomodoro 1: 25 minutes (Focus)
|
||||
☕ Break: 5 minutes
|
||||
🍅 Pomodoro 2: 25 minutes (Focus)
|
||||
☕ Break: 5 minutes
|
||||
🍅 Pomodoro 3: 25 minutes (Focus)
|
||||
☕ Break: 5 minutes
|
||||
🍅 Pomodoro 4: 25 minutes (Focus)
|
||||
🎉 Long Break: 15 minutes
|
||||
|
||||
Total Time: ~2 hours
|
||||
|
||||
Current: 🍅 Pomodoro 1
|
||||
Focus Task: [First planned task]
|
||||
Time Remaining: 25:00
|
||||
```
|
||||
|
||||
2. **AT EACH INTERVAL END**:
|
||||
- Notify completion
|
||||
- Show brief summary
|
||||
- Announce break time or next pomodoro
|
||||
- Track completed pomodoros
|
||||
|
||||
3. **DURING BREAKS**:
|
||||
- Remind user to step away
|
||||
- Show break time remaining
|
||||
- Announce when break ends
|
||||
|
||||
### OUTPUTS
|
||||
- `.timebox/session-[timestamp].md` - Session tracking file
|
||||
- Updated story progress log with session summary
|
||||
- Session history added to `.timebox/history/`
|
||||
- Velocity metrics for future planning
|
||||
|
||||
### RULES
|
||||
- MUST find active story before starting session
|
||||
- MUST calculate accurate checkpoint times
|
||||
- MUST track session start and end timestamps
|
||||
- MUST save session data to tracking file
|
||||
- SHOULD remind at checkpoints if user is active
|
||||
- SHOULD track metrics if commits/tests are mentioned
|
||||
- SHOULD update story progress log at session end
|
||||
- NEVER interrupt user during focused work
|
||||
- ALWAYS provide encouragement and progress acknowledgment
|
||||
- MUST handle pause/resume gracefully
|
||||
|
||||
## Timer Mode Details
|
||||
|
||||
### Standard Mode
|
||||
- Single continuous session with 4 checkpoints (25%, 50%, 75%, 100%)
|
||||
- Flexible focus periods
|
||||
- Checkpoints for progress assessment and plan adjustment
|
||||
- Best for: Larger tasks, exploratory work, complex implementations
|
||||
|
||||
### Pomodoro Mode
|
||||
- Fixed 25-minute work intervals
|
||||
- Mandatory 5-minute breaks between intervals
|
||||
- 15-minute long break after 4 intervals
|
||||
- Structured and disciplined approach
|
||||
- Best for: Deep focus, avoiding burnout, building work habits
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: Standard 2-Hour Session
|
||||
```bash
|
||||
INPUT:
|
||||
/sdd:story-timebox
|
||||
|
||||
OUTPUT:
|
||||
→ Finding active story...
|
||||
→ Located: STORY-2025-003 in development
|
||||
|
||||
What do you want to accomplish in this session?
|
||||
> Implement the task editing feature and write tests
|
||||
|
||||
⏰ TIMEBOX SESSION STARTED
|
||||
═══════════════════════════════════
|
||||
|
||||
Duration: 2 hours (120 minutes)
|
||||
Started: 2:00 PM
|
||||
Ends at: 4:00 PM
|
||||
|
||||
Story: STORY-2025-003 - Task Management System
|
||||
Session Goal: Implement task editing feature and write tests
|
||||
|
||||
📍 CHECKPOINTS:
|
||||
- 25% (2:30 PM): Quick progress check
|
||||
- 50% (3:00 PM): Halfway review
|
||||
- 75% (3:30 PM): Wrap-up warning
|
||||
- 100% (4:00 PM): Session complete
|
||||
|
||||
Timer Mode: Standard
|
||||
|
||||
📋 SESSION PLAN
|
||||
══════════════════════════════════
|
||||
|
||||
Quarter 1 (0-25%): Feature Implementation
|
||||
- [ ] Create TaskEdit Livewire component
|
||||
- [ ] Add edit form with validation
|
||||
|
||||
Quarter 2 (25-50%): Continue Implementation
|
||||
- [ ] Implement update logic in controller
|
||||
- [ ] Add authorization checks
|
||||
|
||||
Quarter 3 (50-75%): Testing
|
||||
- [ ] Write feature tests for edit flow
|
||||
- [ ] Test validation rules
|
||||
- [ ] Test authorization
|
||||
|
||||
Quarter 4 (75-100%): Cleanup & Documentation
|
||||
- [ ] Run all tests and verify passing
|
||||
- [ ] Commit changes with descriptive message
|
||||
- [ ] Update story progress log
|
||||
|
||||
🎯 START NOW: Begin with creating TaskEdit Livewire component
|
||||
```
|
||||
|
||||
### Example 2: Pomodoro Mode
|
||||
```bash
|
||||
INPUT:
|
||||
/sdd:story-timebox 2 pomodoro
|
||||
|
||||
OUTPUT:
|
||||
→ Finding active story...
|
||||
→ Located: STORY-2025-005 in development
|
||||
|
||||
What do you want to accomplish in this session?
|
||||
> Refactor TaskManager component to reduce complexity
|
||||
|
||||
🍅 POMODORO MODE ACTIVE
|
||||
═══════════════════════════════════
|
||||
|
||||
Session Structure:
|
||||
🍅 Pomodoro 1: 25 minutes (Focus)
|
||||
☕ Break: 5 minutes
|
||||
🍅 Pomodoro 2: 25 minutes (Focus)
|
||||
☕ Break: 5 minutes
|
||||
🍅 Pomodoro 3: 25 minutes (Focus)
|
||||
☕ Break: 5 minutes
|
||||
🍅 Pomodoro 4: 25 minutes (Focus)
|
||||
🎉 Long Break: 15 minutes
|
||||
|
||||
Total Time: ~2 hours
|
||||
|
||||
Story: STORY-2025-005 - Code Refactoring
|
||||
Session Goal: Refactor TaskManager component to reduce complexity
|
||||
|
||||
🍅 POMODORO 1 (25:00)
|
||||
Focus: Extract reusable methods from TaskManager
|
||||
- [ ] Identify duplicate code blocks
|
||||
- [ ] Create private helper methods
|
||||
|
||||
🎯 START NOW: Begin analyzing TaskManager for duplication
|
||||
|
||||
[After 25 minutes]
|
||||
✅ POMODORO 1 COMPLETE
|
||||
|
||||
Nice work! Take a 5-minute break.
|
||||
☕ Break time: 5:00
|
||||
|
||||
Next: 🍅 Pomodoro 2 - Continue refactoring
|
||||
```
|
||||
|
||||
### Example 3: Short 30-Minute Session
|
||||
```bash
|
||||
INPUT:
|
||||
/sdd:story-timebox 0.5
|
||||
|
||||
OUTPUT:
|
||||
→ Finding active story...
|
||||
→ Located: STORY-2025-007 in development
|
||||
|
||||
What do you want to accomplish in this session?
|
||||
> Add validation rules to API endpoints
|
||||
|
||||
⏰ TIMEBOX SESSION STARTED
|
||||
═══════════════════════════════════
|
||||
|
||||
Duration: 0.5 hours (30 minutes)
|
||||
Started: 10:00 AM
|
||||
Ends at: 10:30 AM
|
||||
|
||||
Story: STORY-2025-007 - REST API Development
|
||||
Session Goal: Add validation rules to API endpoints
|
||||
|
||||
📍 CHECKPOINTS:
|
||||
- 50% (10:15 AM): Halfway check
|
||||
- 100% (10:30 AM): Session complete
|
||||
|
||||
Timer Mode: Standard (short session - fewer checkpoints)
|
||||
|
||||
📋 SESSION PLAN
|
||||
══════════════════════════════════
|
||||
|
||||
First Half (0-50%): Implementation
|
||||
- [ ] Add validation rules to TaskController
|
||||
- [ ] Add validation rules to CategoryController
|
||||
|
||||
Second Half (50-100%): Testing & Wrap-up
|
||||
- [ ] Test validation with invalid data
|
||||
- [ ] Commit changes
|
||||
|
||||
🎯 START NOW: Add validation to TaskController
|
||||
```
|
||||
|
||||
## Edge Cases
|
||||
|
||||
### No Active Story
|
||||
- DETECT no story in `/docs/stories/development/`
|
||||
- SUGGEST using `/sdd:story-start [id]` to begin a story
|
||||
- OFFER to start session without story tracking
|
||||
- EXIT if user declines
|
||||
|
||||
### Session Already Active
|
||||
- DETECT existing session tracking file
|
||||
- ASK user: Resume previous session or start new?
|
||||
- IF resume: Load previous session state
|
||||
- IF new: Complete previous session first
|
||||
|
||||
### Very Long Duration (> 4 hours)
|
||||
- WARN about diminishing returns beyond 4 hours
|
||||
- SUGGEST breaking into multiple sessions
|
||||
- OFFER to set up with extra break time
|
||||
- ALLOW if user confirms
|
||||
|
||||
### User Goes Silent Mid-Session
|
||||
- Don't interrupt if user is focused
|
||||
- Only mention checkpoints if user becomes active near checkpoint time
|
||||
- Session tracking continues regardless
|
||||
|
||||
## Error Handling
|
||||
- **No active story**: Suggest `/sdd:story-start [id]` or allow storyless session
|
||||
- **Invalid duration**: Suggest valid range (0.5-8 hours)
|
||||
- **Invalid mode**: Suggest "standard" or "pomodoro"
|
||||
- **Session file write error**: Log warning, continue without persistent tracking
|
||||
|
||||
## Performance Considerations
|
||||
- Session tracking is lightweight (< 1KB file)
|
||||
- Checkpoint calculations happen at start (no ongoing computation)
|
||||
- Metrics collected passively from user updates
|
||||
- History files archived monthly to maintain performance
|
||||
|
||||
## Related Commands
|
||||
- `/sdd:story-start [id]` - Begin story before timeboxing
|
||||
- `/sdd:story-save` - Save progress after session
|
||||
- `/sdd:story-quick-check` - Verify work after session
|
||||
- `/sdd:project-status` - View velocity metrics from past sessions
|
||||
|
||||
## Constraints
|
||||
- ✅ MUST find or create active story context
|
||||
- ✅ MUST calculate accurate checkpoint times
|
||||
- ✅ MUST save session data for history
|
||||
- 📋 SHOULD remind at checkpoints (if user active)
|
||||
- 🔧 SHOULD track metrics from user updates
|
||||
- 💾 MUST update story progress log at end
|
||||
- ⚠️ NEVER interrupt during focused work
|
||||
- 🎯 ALWAYS acknowledge progress and provide encouragement
|
||||
- ⏸️ MUST handle pause/resume gracefully
|
||||
- 🧪 SHOULD suggest realistic next sessions based on velocity
|
||||
Reference in New Issue
Block a user