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

Files

Zhongwei Li d97a70be33 Initial commit

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

13 KiB

Raw Permalink Blame History

/sdd:project-phase

Definition

Purpose: Interactively plan the next development phase by gathering user input on desired features and improvements, with optional completion analysis of previous work.

Syntax: /sdd:project-phase [phase_name] [--analyze-only]

Parameters

Parameter	Type	Required	Default	Description	Validation
phase_name	string	No	Auto-generate (e.g., "Phase 2", "v2.0")	Name for the new development phase	Non-empty if provided
--analyze-only	flag	No	false	Only perform analysis without creating new phase documentation	Boolean flag

INSTRUCTION: Interactive Phase Planning with User Input

INPUTS

phase_name: New phase identifier (optional, auto-generated if not provided)
current_brief: Main project brief at /docs/project-context/project-brief.md
user_requirements: Interactive input from user about desired features and improvements
existing_phases: Previous phase documentation in /docs/project-context/phases/
analyze_only: Flag to perform analysis without creating new phase
Optional context: Stories in /docs/stories/completed/, /docs/stories/development/, /docs/stories/review/, /docs/stories/qa/

PROCESS

Phase 1: Environment Setup and Discovery

VERIFY main project brief exists at /docs/project-context/project-brief.md
CREATE /docs/project-context/phases/ directory if missing
SCAN existing phase directories to determine version number
OPTIONAL CONTEXT GATHERING:
- Count stories in each directory (/docs/stories/development/, /docs/stories/review/, /docs/stories/qa/, /docs/stories/completed/)
- Identify recent development patterns for context only

Phase 2: User Consultation for New Phase

PRESENT PROJECT STATUS:
- SHOW current project state and recent development activity
- SUMMARIZE any incomplete work in development/review/qa
- HIGHLIGHT recent completed features and achievements
ASK USER ABOUT NEW PHASE:
- ASK: "Based on the current project state, do you want to plan a new development phase?"
- EXPLAIN what a new phase would involve (planning features, organizing stories, setting goals)
- PROVIDE OPTIONS:
  - "Yes, I want to plan a new phase with specific features and improvements"
  - "No, I want to continue with existing work or make smaller adjustments"
  - "I'm not sure, help me understand what a new phase would look like"
IF USER SAYS NO or UNSURE:
- SUGGEST alternatives like:
  - Continuing existing stories in development
  - Making incremental improvements without formal phase planning
  - Reviewing current work and identifying immediate next steps
- EXIT without creating new phase documentation
- PROVIDE guidance on other available commands for incremental work
IF USER SAYS YES:
- GENERATE phase identifier:
  - IF phase_name provided: USE provided name
  - ELSE: AUTO-GENERATE as "phase-N" where N is next sequential number
- PROCEED to Phase 3 (Interactive Requirements Gathering)

Phase 3: Interactive Requirements Gathering (Only if User Approved New Phase)

USER CONSULTATION - PRIMARY FEATURES:
- ASK: "What are the main features or improvements you want to focus on in this phase?"
- PROMPT for specific areas:
  - New functionality you'd like to add
  - Existing features that need improvement
  - User experience enhancements
  - Performance or technical improvements
- GATHER priority ranking from user input
USER CONSULTATION - TECHNICAL PREFERENCES:
- ASK: "Are there any technical areas you'd like to address?"
  - Code refactoring or cleanup
  - Testing improvements
  - Performance optimizations
  - Security enhancements
  - Accessibility improvements
- UNDERSTAND user's technical comfort level and preferences
USER CONSULTATION - CONSTRAINTS:
- ASK: "What constraints should we consider for this phase?"
  - Time limitations
  - Complexity preferences (simple vs. ambitious)
  - Dependencies on external factors
  - Resource availability
- CLARIFY realistic scope expectations
FEATURE CATEGORIZATION (Based on user input):
- Iteration Features: User-identified improvements to existing functionality
- Extension Features: User-requested new capabilities
- Foundation Features: User-approved technical improvements

Phase 4: Optional Context Analysis

IF USER REQUESTS CONTEXT from previous work:
- REVIEW completed stories for relevant patterns
- ASSESS current technical foundation capabilities
- IDENTIFY any blockers from incomplete work
TECHNICAL FOUNDATION REVIEW (only if relevant to user goals):
- EVALUATE current stack capabilities against user requirements
- IDENTIFY necessary technical prerequisites
- ASSESS feasibility of user-requested features
SUCCESS CRITERIA DEFINITION (collaborative):
- WORK WITH USER to define measurable goals
- SET realistic timelines based on user constraints
- ESTABLISH clear completion criteria for each feature

Phase 5: User Confirmation for Documentation

IF analyze_only flag is TRUE:
- GENERATE analysis report to console
- PROVIDE recommendations without creating files
- SUGGEST optimal phase planning approach
- EXIT without file creation
MANDATORY USER CONFIRMATION (for full phase creation):
- PRESENT complete phase plan summary to user including:
  - Proposed phase name and scope
  - Feature categories and priorities (based on user input)
  - Estimated timeline and effort
  - Technical approach and considerations
  - Story breakdown and dependencies
- ASK EXPLICITLY: "Should I proceed with creating the phase documentation files based on this plan?"
- REQUIRE explicit user approval (yes/no response)
- IF USER DECLINES: Exit without creating any files, suggest refinements
- IF USER APPROVES: Proceed to Phase 6 (Documentation Generation)

Phase 6: Phase Documentation Generation (User Approved Only)

ONLY EXECUTE if user explicitly approved in Phase 5:

CREATE phase directory: /docs/project-context/phases/[phase_name]/

GENERATE phase brief at /docs/project-context/phases/[phase_name]/phase-brief.md:

# Phase Brief: [phase_name]

**Phase Name:** [phase_name]
**Created:** [date]
**Previous Phase Completion:** [completion_percentage]%
**Estimated Duration:** [duration]

## Phase Overview
[Description of this development phase goals and focus]

## Previous Phase Summary
### Recent Development Context
[Brief summary of recent work for context, if relevant]

### Current Project State
[Assessment of current capabilities and foundation]

## Phase Goals & Objectives
### Primary Focus
[Main goal for this phase]

### Success Criteria
[Measurable outcomes and quality gates]

## Feature Categories

### Iteration Features (Improve Existing)
[User-identified improvements to existing functionality with effort estimates]

### Extension Features (Build New)
[User-requested new capabilities with effort estimates and dependencies]

### Foundation Features (Technical Improvements)
[User-approved technical improvements with effort estimates]

## Technical Considerations
### Required Refactoring
[Technical debt and refactoring needs]

### Performance Targets
[Specific performance goals and metrics]

### Quality Improvements
[Testing, accessibility, and code quality goals]

## Dependencies and Prerequisites
[What must be completed before starting each feature category]

## Risk Assessment
[Specific risks for this phase with mitigation strategies]

## Estimated Timeline
[Phase-based implementation plan with milestones]

## Story Planning
[List of stories to be created for this phase]

## Success Metrics
[How to measure phase completion and success]

CREATE story queue at /docs/project-context/phases/[phase_name]/story-queue.md:

# Story Queue: [phase_name]

## Ready for Development
[Stories ready to move to /docs/stories/development/]

## Blocked/Waiting
[Stories waiting for dependencies or decisions]

## Future Consideration
[Stories for later in the phase or next phase]

## Story Dependencies
[Dependency relationships between new stories]

UPDATE main project brief:
- ADD phase summary based on user input
- UPDATE timeline with new phase
- REFERENCE new phase documentation

Phase 7: Story Planning and Organization

USER STORY DEFINITION (based on user requirements):
- CONVERT user requirements into actionable stories
- BREAK DOWN complex features into implementable chunks
- PRIORITIZE based on user preferences and dependencies
STORY QUEUE POPULATION:
- POPULATE story queue with user-defined priorities
- ORGANIZE by user-specified implementation order
- ESTIMATE effort based on user constraints and complexity preferences
EXISTING WORK INTEGRATION:
- REVIEW any incomplete stories for relevance to new phase
- SUGGEST continuation only if aligned with user goals
- IDENTIFY conflicts between existing work and new direction

Phase 8: Final Summary and Next Steps

COMPLETION SUMMARY:
- CONFIRM phase documentation has been created successfully
- SUMMARIZE what was implemented based on user requirements
- HIGHLIGHT key files created and their purposes
GENERATE operation summary with:
- User-defined feature goals and categories
- Estimated timeline based on user constraints
- Implementation approach aligned with user preferences
- Recommended next steps for development
PROVIDE actionable next steps:
- Commands to run to start new phase development
- Story creation recommendations based on user priorities
- Technical setup requirements for user-requested features

OUTPUTS

/docs/project-context/phases/[phase_name]/phase-brief.md: Focused phase documentation
/docs/project-context/phases/[phase_name]/story-queue.md: Prioritized story backlog
Updated /docs/project-context/project-brief.md: Phase completion summary
Console summary: Completion analysis and phase planning results

RULES

MUST preserve all existing project documentation
MUST prioritize user input over automated analysis
MUST ask clarifying questions to understand user requirements
MUST get explicit user approval before creating any new phase documentation
MUST exit gracefully if user does not want a new phase
MUST NOT create individual story files (only queue them)
SHOULD focus on user-defined priorities and goals
SHOULD build upon technical foundation already established
MUST maintain consistency with main project brief
SHOULD provide realistic effort estimates based on user constraints

ERROR HANDLING

Missing project brief: Error and suggest running /sdd:project-brief first
Insufficient user input: Ask clarifying questions to gather requirements
File system errors: Report specific error and suggest manual intervention
Invalid phase name: Sanitize and suggest corrected version

PERFORMANCE CONSIDERATIONS

Large story collections: Process incrementally to avoid memory issues
Complex dependency analysis: Limit analysis to direct dependencies
File I/O optimization: Batch read operations for story analysis

SECURITY CONSIDERATIONS

File permissions: Ensure write access to project-context directory
Path validation: Sanitize all file paths and directory names
Data integrity: Validate story file parsing before analysis

INTEGRATION WITH EXISTING WORKFLOW

Before: Must have existing project brief
After: Use /sdd:story-new to create individual stories from queue
Complements: Works with /sdd:project-brief for major updates
Feeds into: Standard story development workflow

/sdd:project-brief: Update main project documentation
/sdd:story-new: Create individual stories from phase queue
/sdd:project-status: View current development state
/sdd:story-relationships: Manage dependencies between stories

VERSION HISTORY

v1.0: Initial implementation with completion analysis and phase planning
v1.1: Updated to prioritize interactive user input over automated analysis
v1.2: Added mandatory user consultation before phase creation and explicit approval before documentation

13 KiB Raw Permalink Blame History