zhongwei/gh-ninthspace-claude-code-marketplace-sdd

Files

Zhongwei Li d97a70be33 Initial commit

2025-11-30 08:44:27 +08:00

15 KiB

Raw Blame History

/sdd:story-timebox

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

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
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
ASK user for session goal:
- "What do you want to accomplish in this session?"
- RECORD goal for tracking

Phase 2: Session Planning

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
GENERATE session plan based on goal:
- Break down goal into 4 quarterly segments
- Suggest specific tasks for each quarter
- Include testing and cleanup phases
CREATE session tracking file:
- Location: .timebox/session-[timestamp].md
- Contains: Story ID, goal, plan, checkpoints

Phase 3: Session Start Display

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]

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]

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:

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]

UPDATE session tracking file:
- Log checkpoint reached
- Record user's progress update
- Note any plan adjustments

Phase 5: Session Metrics Tracking

Throughout session, TRACK:

Code Metrics (if user commits/shows changes):
- Lines added/removed
- Files modified
- Commits made
Test Metrics (if tests run):
- Tests added
- Tests passing/failing
- Coverage changes
Progress Metrics:
- Tasks completed vs planned
- Checkpoint adherence
- Goal achievement percentage

Phase 6: Session Interruption Handling

IF user says "pause", "stop", "brb", or similar:

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"

SAVE pause state to session tracking file

IF user returns:

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":

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! 🎉

ASK user for session notes:
- "What went well this session?"
- "What was challenging?"
- "What should you focus on next time?"
UPDATE story progress log:
- Append session summary to story file
- Note tasks completed and time spent
- Record any blockers or notes
SAVE session to history:
- Complete session tracking file
- Add to .timebox/history/ for velocity analysis
SUGGEST next session:
- Based on progress rate
- Consider remaining work
- Recommend duration and focus

Phase 8: Pomodoro Mode (Special Handling)

IF mode = pomodoro:

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

AT EACH INTERVAL END:
- Notify completion
- Show brief summary
- Announce break time or next pomodoro
- Track completed pomodoros
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

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

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

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

/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

15 KiB Raw Blame History