zhongwei/gh-ninthspace-claude-code-marketplace-sdd
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d97a70be331ab765e3a939a4d772797f37f783bc
gh-ninthspace-claude-code-m…/commands/project-stories.md
Zhongwei Li d97a70be33 Initial commit
2025-11-30 08:44:27 +08:00

17 KiB
Raw Blame History

/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
Reference in New Issue View Git Blame Copy Permalink