/sdd:project-stories

Meta

• Version: 2.0
• Category: project-management
• Complexity: medium
• Purpose: Display detailed story breakdown with dependencies and implementation order

Definition

Purpose: List all stories for the current project with comprehensive dependency analysis, status tracking, and implementation recommendations.

Syntax: /sdd:project-stories

Parameters

None

Behavior

Step 1: Project Brief Verification

1. CHECK for project brief at /docs/project-context/project-brief.md
2. IF no project brief exists:
   • SUGGEST using /sdd:project-brief to create one
   • EXIT with guidance message

Step 2: Project Context Loading

1. READ project brief to extract:

   • Project title and objectives
   • Story categorization (Core/Enhancement/Future)
   • Overall timeline and implementation phases
   • Project goals and success criteria

2. READ story relationships file at /docs/project-context/story-relationships.md:

   • Dependency mapping between stories
   • Priority matrix with effort estimates
   • Implementation phase groupings
   • Critical path identification

Step 3: Story Collection

SCAN all story directories to collect all project stories:

Directories:

• /docs/stories/development/ - Active implementation
• /docs/stories/review/ - Code review stage
• /docs/stories/qa/ - Quality assurance testing
• /docs/stories/completed/ - Finished and shipped
• /docs/stories/backlog/ - Planned but not started (if exists)

FOR EACH story file:

• EXTRACT story ID, title, status
• READ dependencies and effort estimates
• IDENTIFY priority level (Core/Enhancement/Future)
• NOTE current stage in workflow

Step 4: Story Analysis and Categorization

1. GROUP stories by priority:

   • Core Stories: Must-have functionality (highest priority)
   • Enhancement Stories: Should-have features (medium priority)
   • Future Stories: Could-have improvements (lower priority)

2. ANALYZE dependencies:

   • BUILD dependency graph
   • IDENTIFY blocked stories (waiting on dependencies)
   • FIND ready-to-start stories (all dependencies met)
   • DETECT circular dependencies (if any)

3. CALCULATE metrics:

   • Total story count by category
   • Completion percentage per category
   • Overall project progress
   • Stories per status (Done/In Progress/Ready/Blocked)

Step 5: Formatted Story Display

GENERATE comprehensive story breakdown:

🏗️  PROJECT: [Title]
====================

📊 OVERVIEW
- Total Stories: 8
- Completed: 3 ✅
- In Progress: 2 🔄
- Pending: 3 ⏳
- Overall Progress: 37% ████░░░░░░

🎯 CORE STORIES (Must Have)
┌─────────────┬──────────────────────────────┬──────────────┬─────────┬──────────┐
│ Story ID    │ Title                        │ Dependencies │ Status  │ Effort   │
├─────────────┼──────────────────────────────┼──────────────┼─────────┼──────────┤
│ STORY-001   │ Shopping cart persistence    │ None         │ ✅ Done │ Medium   │
│ STORY-002   │ Payment processing           │ STORY-001    │ ✅ Done │ Large    │
│ STORY-003   │ Order confirmation           │ STORY-002    │ 🔄 Dev  │ Medium   │
│ STORY-004   │ Inventory validation         │ STORY-001    │ ⏳ Ready│ Small    │
└─────────────┴──────────────────────────────┴──────────────┴─────────┴──────────┘

🚀 ENHANCEMENT STORIES (Should Have)
┌─────────────┬──────────────────────────────┬──────────────┬─────────┬──────────┐
│ STORY-005   │ Tax calculation              │ STORY-003    │ ⏳ Wait │ Medium   │
│ STORY-006   │ Shipping options             │ STORY-003    │ ⏳ Wait │ Large    │
│ STORY-007   │ Promo code system            │ STORY-002    │ ✅ Done │ Medium   │
└─────────────┴──────────────────────────────┴──────────────┴─────────┴──────────┘

🔮 FUTURE STORIES (Could Have)
┌─────────────┬──────────────────────────────┬──────────────┬─────────┬──────────┐
│ STORY-008   │ Order tracking               │ STORY-003    │ ⏳ Wait │ Large    │
└─────────────┴──────────────────────────────┴──────────────┴─────────┴──────────┘

🗂️  DEPENDENCY FLOW
STORY-001 (✅) → STORY-002 (✅) → STORY-003 (🔄)
    ↓                              ↓
STORY-004 (⏳)                  STORY-005 (⏳)
                                   ↓
                               STORY-006 (⏳)
                                   ↓
                               STORY-008 (⏳)

STORY-007 (✅) ← STORY-002 (✅)

📅 SUGGESTED NEXT ACTIONS
1. 🔄 Continue STORY-003 (Order confirmation) - Currently in development
2. ✅ Ready: STORY-004 (Inventory validation) - No blockers
3. ⏸️  Blocked: STORY-005, STORY-006, STORY-008 - Wait for STORY-003

💡 COMMANDS TO USE
1. /sdd:story-implement STORY-004  # Start ready story
2. /sdd:story-continue STORY-003   # Resume current work
3. /sdd:story-status               # Check individual story details

Step 6: Opportunity Identification

1. IDENTIFY ready-to-start stories:

   • All dependencies completed
   • No blockers present
   • Can be started immediately

2. FIND blocked stories:

   • List dependencies that must complete first
   • Show which story is blocking each blocked story
   • Estimate when blockers might be resolved

3. HIGHLIGHT current work in progress:

   • Active development stories
   • Stories in review or QA
   • Recently completed stories

4. DETECT parallelization opportunities:

   • Stories with no shared dependencies
   • Independent work streams
   • Team capacity considerations

Step 7: Branch and Integration Information

IF git branch information available:

• LIST active branches for in-progress stories
• IDENTIFY merge conflicts or integration points
• SUGGEST branch cleanup for completed stories

Step 8: Project Health Metrics

CALCULATE and DISPLAY:

Velocity Metrics:

• Stories completed per week (average)
• Current sprint/phase progress
• Estimated completion date

Risk Factors:

• Number of blocked stories
• Large unstarted critical stories
• Dependencies on slow-moving work
• Long-running stories (potential issues)

Quality Metrics:

• Stories awaiting review
• Stories in QA
• Recent failure rates (if available)

Step 9: Simplified View (No Project Brief)

IF no project brief exists, DISPLAY simplified listing:

📊 STORY OVERVIEW (SIMPLIFIED)
===============================

📁 Stories Found:
- Development: [count] stories
- Review: [count] stories
- QA: [count] stories
- Completed: [count] stories
- Total: [count] stories

[List of all stories with basic info]

💡 RECOMMENDATION
Create a project brief for better organization:
→ /sdd:project-brief

This will enable:
- Story prioritization
- Dependency tracking
- Timeline planning
- Progress metrics

Output Format

Standard Output

Comprehensive story display including:

• Overview with progress metrics
• Categorized story tables (Core/Enhancement/Future)
• Visual dependency flow diagram
• Status indicators (✅ 🔄 ⏳ ⏸️)
• Suggested next actions
• Relevant commands

Simplified Output

Basic story listing when project brief is missing:

• Count by directory
• Simple list of all stories
• Recommendation to create project structure

Examples

Example 1: E-commerce Checkout Project

INPUT:
/sdd:project-stories

OUTPUT:
🏗️  PROJECT: E-commerce Checkout Flow
====================================

📊 OVERVIEW
- Total Stories: 8
- Completed: 3 ✅
- In Progress: 2 🔄
- Pending: 3 ⏳
- Overall Progress: 37% ████░░░░░░

🎯 CORE STORIES (Must Have)
┌─────────────┬──────────────────────────────┬──────────────┬─────────┬──────────┐
│ STORY-CHK-001 │ Shopping cart persistence  │ None         │ ✅ Done │ Medium   │
│ STORY-CHK-002 │ Payment processing         │ STORY-CHK-001│ ✅ Done │ Large    │
│ STORY-CHK-003 │ Order confirmation         │ STORY-CHK-002│ 🔄 Dev  │ Medium   │
│ STORY-CHK-004 │ Inventory validation       │ STORY-CHK-001│ ⏳ Ready│ Small    │
└─────────────┴──────────────────────────────┴──────────────┴─────────┴──────────┘

🚀 ENHANCEMENT STORIES (Should Have)
┌─────────────┬──────────────────────────────┬──────────────┬─────────┬──────────┐
│ STORY-CHK-005 │ Tax calculation            │ STORY-CHK-003│ ⏳ Wait │ Medium   │
│ STORY-CHK-006 │ Shipping options           │ STORY-CHK-003│ ⏳ Wait │ Large    │
│ STORY-CHK-007 │ Promo code system          │ STORY-CHK-002│ ✅ Done │ Medium   │
└─────────────┴──────────────────────────────┴──────────────┴─────────┴──────────┘

🔮 FUTURE STORIES (Could Have)
┌─────────────┬──────────────────────────────┬──────────────┬─────────┬──────────┐
│ STORY-CHK-008 │ Order tracking             │ STORY-CHK-003│ ⏳ Wait │ Large    │
└─────────────┴──────────────────────────────┴──────────────┴─────────┴──────────┘

🗂️  DEPENDENCY FLOW
STORY-CHK-001 (✅) → STORY-CHK-002 (✅) → STORY-CHK-003 (🔄)
    ↓                                        ↓
STORY-CHK-004 (⏳)                      STORY-CHK-005 (⏳)
                                             ↓
                                        STORY-CHK-006 (⏳)
                                             ↓
                                        STORY-CHK-008 (⏳)

STORY-CHK-007 (✅) ← STORY-CHK-002 (✅)

📅 SUGGESTED NEXT ACTIONS
1. 🔄 Continue STORY-CHK-003 (Order confirmation) - Currently in development
2. ✅ Ready: STORY-CHK-004 (Inventory validation) - No blockers, can start immediately
3. ⏸️  Blocked: STORY-CHK-005, STORY-CHK-006, STORY-CHK-008 - Waiting for STORY-CHK-003

💡 COMMANDS TO USE
1. /sdd:story-implement STORY-CHK-004  # Start ready story
2. /sdd:story-continue STORY-CHK-003   # Resume current work
3. /sdd:story-status                   # Check individual story details

Example 2: Project Without Brief

INPUT:
/sdd:project-stories

OUTPUT:
📊 STORY OVERVIEW (SIMPLIFIED)
===============================

📁 Stories Found:
- Development: 2 stories
- Review: 1 story
- QA: 1 story
- Completed: 3 stories
- Total: 7 stories

Stories:
1. STORY-001: User authentication (✅ Completed)
2. STORY-002: Dashboard layout (✅ Completed)
3. STORY-003: Data export (✅ Completed)
4. STORY-004: Advanced filters (🔄 Development)
5. STORY-005: Report generation (🔄 Development)
6. STORY-006: Email notifications (🔍 Review)
7. STORY-007: Mobile responsive (🧪 QA)

💡 RECOMMENDATION
Create a project brief for better organization:
→ /sdd:project-brief

This will enable:
- Story prioritization (Core/Enhancement/Future)
- Dependency tracking and visualization
- Timeline planning and velocity metrics
- Progress tracking and health metrics

Example 3: All Stories Blocked

INPUT:
/sdd:project-stories

OUTPUT:
🏗️  PROJECT: Mobile App Dashboard
==================================

📊 OVERVIEW
- Total Stories: 5
- Completed: 1 ✅
- In Progress: 1 🔄
- Blocked: 3 ⚠️
- Overall Progress: 20% ██░░░░░░░░

⚠️  CRITICAL: Multiple Blocked Stories

🎯 CORE STORIES (Must Have)
┌─────────────┬──────────────────────────────┬──────────────┬─────────┬──────────┐
│ STORY-001   │ API authentication           │ None         │ ✅ Done │ Large    │
│ STORY-002   │ Data synchronization         │ STORY-001    │ 🔄 Dev  │ Large    │
│ STORY-003   │ Offline mode                 │ STORY-002    │ ⚠️  Wait│ XLarge   │
│ STORY-004   │ Push notifications           │ STORY-002    │ ⚠️  Wait│ Medium   │
│ STORY-005   │ Analytics dashboard          │ STORY-002    │ ⚠️  Wait│ Large    │
└─────────────┴──────────────────────────────┴──────────────┴─────────┴──────────┘

🗂️  DEPENDENCY FLOW
STORY-001 (✅) → STORY-002 (🔄) → STORY-003 (⚠️)
                     ↓
                 STORY-004 (⚠️)
                     ↓
                 STORY-005 (⚠️)

⚠️  BLOCKER ANALYSIS
- 3 stories blocked by STORY-002 (Data synchronization)
- Focus needed on completing STORY-002 to unblock pipeline
- Large story (STORY-003) waiting - may need breakdown

📅 RECOMMENDED ACTIONS
1. 🔥 PRIORITY: Complete STORY-002 to unblock 3 downstream stories
2. 💡 Consider breaking down STORY-003 (XLarge) into smaller stories
3. 📋 Review STORY-002 progress and identify any blockers

💡 COMMANDS TO USE
1. /sdd:story-continue STORY-002   # Focus on unblocking work
2. /sdd:story-status STORY-002     # Check detailed progress
3. /sdd:project-status             # Overall project health check

Edge Cases

No Stories Found

• DISPLAY message about empty project
• SUGGEST creating first story with /sdd:story-new
• RECOMMEND running /sdd:project-brief for planning

Circular Dependencies

• DETECT circular dependency loops
• HIGHLIGHT stories involved in cycle
• SUGGEST breaking circular dependencies
• PROVIDE guidance on refactoring story structure

All Stories Complete

• CONGRATULATE on completion
• SHOW final statistics and velocity
• SUGGEST next phase planning with /sdd:project-phase
• RECOMMEND project retrospective

Large Number of Stories

• GROUP stories by phase/sprint if available
• PROVIDE filtering options
• SUMMARIZE rather than showing full tables
• SUGGEST using /sdd:story-status for individual details

Error Handling

• Missing project brief: Suggest /sdd:project-brief, continue with simplified view
• Corrupted story files: Skip corrupted files, log warnings, continue processing
• Missing dependencies: Highlight unresolved dependencies, suggest fixes
• Permission errors: Report specific files with access issues

Performance Considerations

• Story file reads optimized with metadata-only scanning
• Large collections (50+ stories) use progressive loading
• Dependency graph calculation cached per invocation
• Table formatting optimizes for terminal width

Related Commands

• /sdd:project-brief - Create or update project documentation
• /sdd:project-status - High-level project progress view
• /sdd:project-phase - Plan next development phase
• /sdd:story-status - Individual story detailed view
• /sdd:story-implement [id] - Start working on a ready story
• /sdd:story-continue - Resume active work

Constraints

• ✅ MUST group stories by priority category
• ✅ MUST show dependency relationships visually
• ✅ MUST identify ready-to-start and blocked stories
• 📊 SHOULD calculate accurate progress metrics
• 🎯 SHOULD provide actionable next steps
• ⚠️ MUST highlight critical blockers clearly
• 🔄 SHOULD show parallelization opportunities