Initial commit
This commit is contained in:
Zhongwei Li
455
commands/story-refactor.md
Normal file
455
commands/story-refactor.md
Normal file
@@ -0,0 +1,455 @@
|
||||
# /sdd:story-refactor
|
||||
|
||||
## Meta
|
||||
- Version: 2.0
|
||||
- Category: story-management
|
||||
- Complexity: high
|
||||
- Purpose: Create refactoring story based on code analysis and project standards
|
||||
|
||||
## Definition
|
||||
**Purpose**: Analyze codebase against project standards and create a prioritized refactoring story with specific, actionable requirements.
|
||||
|
||||
**Syntax**: `/sdd:story-refactor [objective]`
|
||||
|
||||
## Parameters
|
||||
| Parameter | Type | Required | Default | Description | Validation |
|
||||
|-----------|------|----------|---------|-------------|------------|
|
||||
| objective | string | No | comprehensive | Refactoring focus area or general analysis | Any text phrase |
|
||||
|
||||
## INSTRUCTION: Create Refactoring Story
|
||||
|
||||
### INPUTS
|
||||
- objective: Optional refactoring focus (e.g., "improve performance", "reduce complexity")
|
||||
- Project context from `/docs/project-context/` directory
|
||||
- Current codebase state
|
||||
- Active stories from `/docs/stories/development/`
|
||||
|
||||
### PROCESS
|
||||
|
||||
#### Phase 1: Project Context Loading
|
||||
1. **CHECK** if `/docs/project-context/` directory exists
|
||||
2. IF missing:
|
||||
- SUGGEST running `/sdd:project-init` first
|
||||
- EXIT with initialization guidance
|
||||
3. **LOAD** project context from:
|
||||
- `/docs/project-context/coding-standards.md` - Code quality rules and thresholds
|
||||
- `/docs/project-context/technical-stack.md` - Framework patterns and best practices
|
||||
- `/docs/project-context/development-process.md` - Quality requirements
|
||||
|
||||
#### Phase 2: Objective Definition
|
||||
1. **PARSE** optional objective parameter
|
||||
2. IF no objective provided:
|
||||
- SET analysis mode = comprehensive
|
||||
- ANALYZE all code quality dimensions
|
||||
3. IF objective provided:
|
||||
- MAP objective to analysis focus areas:
|
||||
* "improve performance" → Database queries, N+1, caching, assets
|
||||
* "reduce complexity" → Cyclomatic complexity, nesting, method length
|
||||
* "extract reusable components" → Duplicate code, large components
|
||||
* "improve accessibility" → ARIA, keyboard nav, screen readers
|
||||
* "optimize for mobile" → Responsive design, touch, performance
|
||||
* Custom → Interpret and adapt analysis
|
||||
- PRIORITIZE findings aligned with objective
|
||||
|
||||
#### Phase 3: Code Analysis
|
||||
1. **ANALYZE** codebase using DISCOVERED standards from project context:
|
||||
|
||||
**Structure Issues**:
|
||||
- SCAN for functions exceeding length limits (from coding-standards.md)
|
||||
- CHECK nesting depth against complexity thresholds
|
||||
- IDENTIFY duplicate code blocks
|
||||
- FLAG complex conditionals
|
||||
|
||||
**Naming Conventions**:
|
||||
- VERIFY variables follow naming patterns
|
||||
- CHECK consistency with style guide
|
||||
- VALIDATE function naming conventions
|
||||
|
||||
**Framework Patterns** (from technical-stack.md):
|
||||
- Laravel: Eloquent patterns, validation, authorization
|
||||
- React: Hooks patterns, prop validation
|
||||
- Vue: Composition API, reactivity
|
||||
- Django: MVT patterns, form validation
|
||||
- Express: Middleware patterns, error handling
|
||||
- [DISCOVERED framework]: Apply specific patterns
|
||||
|
||||
**Error Handling**:
|
||||
- CHECK error boundaries exist (per framework)
|
||||
- VERIFY comprehensive error handling
|
||||
- VALIDATE loading states present
|
||||
|
||||
**Performance**:
|
||||
- IDENTIFY database N+1 queries
|
||||
- CHECK for missing caching opportunities
|
||||
- ANALYZE asset optimization
|
||||
- MEASURE component render efficiency
|
||||
|
||||
**Accessibility** (if relevant):
|
||||
- VERIFY ARIA attributes present
|
||||
- CHECK keyboard navigation support
|
||||
- VALIDATE screen reader compatibility
|
||||
- TEST focus management
|
||||
|
||||
2. **PRIORITIZE** findings:
|
||||
|
||||
IF comprehensive mode:
|
||||
- Priority 1: Security/bug issues requiring immediate attention
|
||||
- Priority 2: Maintainability issues affecting development velocity
|
||||
- Priority 3: Style and optimization improvements
|
||||
|
||||
IF objective-focused mode:
|
||||
- Priority 1: Changes directly supporting objective
|
||||
- Priority 2: Critical security/bug issues (non-conflicting)
|
||||
- Priority 3: Supporting improvements complementing objective
|
||||
|
||||
#### Phase 4: Story ID Generation
|
||||
1. **GENERATE** story ID in format `STORY-YYYY-NNN`:
|
||||
- YYYY = current year
|
||||
- NNN = next available number
|
||||
2. **CHECK** for existing IDs across all story directories
|
||||
3. **ENSURE** uniqueness
|
||||
|
||||
#### Phase 5: Story File Creation
|
||||
1. **ENSURE** `/docs/stories/backlog/` directory exists
|
||||
2. **CREATE** story file at `/docs/stories/backlog/[story-id].md`
|
||||
3. **POPULATE** refactoring story template with:
|
||||
|
||||
- Story ID and title (auto-generated based on objective)
|
||||
- Status: backlog
|
||||
- Today's date as "Started" date
|
||||
- Refactoring objective (clear goal statement)
|
||||
- Background (why refactoring needed, analysis summary)
|
||||
- Analysis Findings (organized by priority, with file:line references)
|
||||
- Requirements (specific, actionable refactoring tasks)
|
||||
- Acceptance Criteria (testable completion criteria)
|
||||
- Implementation Notes (technical guidance, patterns to follow)
|
||||
- Testing Requirements (verify functionality maintained)
|
||||
- Risk Assessment (potential risks, mitigation strategies)
|
||||
- Impact Analysis (affected components, tests, dependencies)
|
||||
|
||||
4. **REFERENCE** analysis findings:
|
||||
- Include file paths and line numbers
|
||||
- Show before/after code examples
|
||||
- Note pattern violations with framework references
|
||||
- Link to relevant coding standard sections
|
||||
|
||||
#### Phase 6: Completion Summary
|
||||
1. **DISPLAY** refactoring summary:
|
||||
```
|
||||
✅ Refactoring Story Created
|
||||
═══════════════════════════════════
|
||||
|
||||
Story ID: [STORY-YYYY-NNN]
|
||||
Title: [Auto-generated Title]
|
||||
Location: /docs/stories/backlog/[story-id].md
|
||||
Status: backlog
|
||||
|
||||
Analysis Mode: [Comprehensive / Objective-focused: {objective}]
|
||||
|
||||
Findings:
|
||||
- Priority 1 (Critical): [count] issues
|
||||
- Priority 2 (Important): [count] issues
|
||||
- Priority 3 (Nice to have): [count] improvements
|
||||
|
||||
Files Affected: [count] files
|
||||
Estimated Complexity: [Low/Medium/High]
|
||||
```
|
||||
|
||||
2. **SUGGEST** next steps:
|
||||
```
|
||||
💡 NEXT STEPS:
|
||||
1. Review story in /docs/stories/backlog/[story-id].md
|
||||
2. /sdd:story-start [story-id] # Move to development when ready
|
||||
3. /sdd:project-status # View all stories
|
||||
```
|
||||
|
||||
### OUTPUTS
|
||||
- `/docs/stories/backlog/[story-id].md` - New refactoring story with comprehensive analysis
|
||||
- Analysis summary with prioritized findings
|
||||
|
||||
### RULES
|
||||
- MUST generate unique story ID across all directories
|
||||
- MUST analyze using DISCOVERED project standards (no assumptions)
|
||||
- MUST prioritize findings by objective if provided
|
||||
- MUST include file paths and line numbers in findings
|
||||
- MUST provide specific, actionable refactoring tasks
|
||||
- SHOULD include before/after code examples
|
||||
- SHOULD reference framework patterns from technical-stack.md
|
||||
- NEVER suggest refactoring without analysis evidence
|
||||
- ALWAYS include risk assessment for breaking changes
|
||||
- MUST verify all existing tests will pass post-refactoring
|
||||
|
||||
## Refactoring Story Template
|
||||
|
||||
```markdown
|
||||
# [STORY-ID]: [Refactoring Title]
|
||||
|
||||
## Status: backlog
|
||||
**Started:** [Today's Date]
|
||||
**Completed:**
|
||||
**Branch:** (none - in backlog)
|
||||
|
||||
## Objective
|
||||
[Clear statement of refactoring goal based on analysis]
|
||||
|
||||
## Background
|
||||
[Why this refactoring is needed - analysis context, pain points, violations found]
|
||||
|
||||
## Analysis Findings
|
||||
|
||||
### Priority 1: Critical
|
||||
- [ ] **[File:Line]**: [Issue description]
|
||||
- Current: [Code example or pattern]
|
||||
- Standard: [Expected pattern from coding-standards.md]
|
||||
- Impact: [Why this matters]
|
||||
|
||||
### Priority 2: Important
|
||||
- [ ] **[File:Line]**: [Issue description]
|
||||
- Current: [Code example]
|
||||
- Suggested: [Improved pattern]
|
||||
- Benefit: [Improvement gained]
|
||||
|
||||
### Priority 3: Nice to Have
|
||||
- [ ] **[File:Line]**: [Improvement opportunity]
|
||||
- Enhancement: [What to improve]
|
||||
- Justification: [Why it helps]
|
||||
|
||||
## Requirements
|
||||
|
||||
### R1: [Requirement Title]
|
||||
**What**: [Specific change needed]
|
||||
**Why**: [Business/technical justification]
|
||||
**How**: [Suggested approach or pattern]
|
||||
**Tests**: [Impact on existing tests]
|
||||
**Dependencies**: [Related components]
|
||||
|
||||
### R2: [Requirement Title]
|
||||
[Same structure as R1]
|
||||
|
||||
## Acceptance Criteria
|
||||
- [ ] All Priority 1 issues resolved
|
||||
- [ ] Code quality metrics maintained or improved
|
||||
- [ ] All existing functionality works identically
|
||||
- [ ] All tests pass (no failures introduced)
|
||||
- [ ] Code follows [framework] patterns from technical-stack.md
|
||||
- [ ] Performance metrics maintained or improved
|
||||
- [ ] Documentation updated where necessary
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
**Approach**: [Recommended refactoring strategy]
|
||||
**Stack**: [Auto-populated from technical-stack.md]
|
||||
**Patterns**: [Framework-specific patterns to apply]
|
||||
**Tools**: [Linters, formatters, static analysis tools to use]
|
||||
|
||||
## Testing Requirements
|
||||
|
||||
### Existing Tests
|
||||
- [ ] All unit tests pass
|
||||
- [ ] All integration tests pass
|
||||
- [ ] All E2E tests pass
|
||||
- [ ] No regressions in test coverage
|
||||
|
||||
### New Tests
|
||||
- [ ] [New test scenario 1]
|
||||
- [ ] [New test scenario 2]
|
||||
|
||||
### Manual Testing
|
||||
- [ ] [Manual verification step 1]
|
||||
- [ ] [Manual verification step 2]
|
||||
|
||||
## Risk Assessment
|
||||
|
||||
### High Risk
|
||||
- **[Risk description]**: [Mitigation strategy]
|
||||
|
||||
### Medium Risk
|
||||
- **[Risk description]**: [Mitigation strategy]
|
||||
|
||||
### Low Risk
|
||||
- **[Risk description]**: [Mitigation strategy]
|
||||
|
||||
## Impact Analysis
|
||||
|
||||
**Components Affected**: [List of components/modules]
|
||||
**Tests Affected**: [List of test files]
|
||||
**Dependencies**: [External dependencies or other stories]
|
||||
**Breaking Changes**: [Yes/No - details if yes]
|
||||
|
||||
## Progress Log
|
||||
- [Today]: Created refactoring story from code analysis
|
||||
|
||||
## Rollback Plan
|
||||
[How to rollback if issues arise during refactoring]
|
||||
|
||||
## Lessons Learned
|
||||
[To be filled when complete]
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: Comprehensive Refactoring
|
||||
```bash
|
||||
INPUT:
|
||||
/sdd:story-refactor
|
||||
|
||||
OUTPUT:
|
||||
→ Checking project context...
|
||||
→ Loading coding standards and framework patterns...
|
||||
→ Analyzing codebase comprehensively...
|
||||
→ Found 23 issues across 8 files
|
||||
|
||||
✅ Refactoring Story Created
|
||||
═══════════════════════════════════
|
||||
|
||||
Story ID: STORY-2025-012
|
||||
Title: Comprehensive Code Quality Improvements
|
||||
Location: /docs/stories/backlog/STORY-2025-012.md
|
||||
Status: backlog
|
||||
|
||||
Analysis Mode: Comprehensive
|
||||
|
||||
Findings:
|
||||
- Priority 1 (Critical): 3 issues
|
||||
- Priority 2 (Important): 12 issues
|
||||
- Priority 3 (Nice to have): 8 improvements
|
||||
|
||||
Files Affected: 8 files
|
||||
Estimated Complexity: High
|
||||
|
||||
💡 NEXT STEPS:
|
||||
1. Review story in /docs/stories/backlog/STORY-2025-012.md
|
||||
2. /sdd:story-start STORY-2025-012 # Move to development when ready
|
||||
3. /sdd:project-status # View all stories
|
||||
```
|
||||
|
||||
### Example 2: Performance-Focused Refactoring
|
||||
```bash
|
||||
INPUT:
|
||||
/sdd:story-refactor improve performance
|
||||
|
||||
OUTPUT:
|
||||
→ Checking project context...
|
||||
→ Loading coding standards and framework patterns...
|
||||
→ Analyzing for performance issues...
|
||||
→ Scanning database queries, caching, assets...
|
||||
→ Found 7 performance issues across 5 files
|
||||
|
||||
✅ Refactoring Story Created
|
||||
═══════════════════════════════════
|
||||
|
||||
Story ID: STORY-2025-013
|
||||
Title: Performance Optimization Refactoring
|
||||
Location: /docs/stories/backlog/STORY-2025-013.md
|
||||
Status: backlog
|
||||
|
||||
Analysis Mode: Objective-focused (improve performance)
|
||||
|
||||
Findings:
|
||||
- Priority 1 (Performance): 7 issues
|
||||
• 3 N+1 query problems
|
||||
• 2 missing cache opportunities
|
||||
• 2 unoptimized asset loads
|
||||
- Priority 2 (Critical): 0 issues
|
||||
- Priority 3 (Supporting): 2 improvements
|
||||
|
||||
Files Affected: 5 files
|
||||
Estimated Complexity: Medium
|
||||
|
||||
💡 NEXT STEPS:
|
||||
1. Review story in /docs/stories/backlog/STORY-2025-013.md
|
||||
2. /sdd:story-start STORY-2025-013 # Move to development when ready
|
||||
3. /sdd:project-status # View all stories
|
||||
```
|
||||
|
||||
### Example 3: Accessibility Refactoring
|
||||
```bash
|
||||
INPUT:
|
||||
/sdd:story-refactor improve accessibility
|
||||
|
||||
OUTPUT:
|
||||
→ Checking project context...
|
||||
→ Analyzing ARIA, keyboard nav, screen reader support...
|
||||
→ Found 15 accessibility issues across 6 components
|
||||
|
||||
✅ Refactoring Story Created
|
||||
═══════════════════════════════════
|
||||
|
||||
Story ID: STORY-2025-014
|
||||
Title: Accessibility Compliance Refactoring
|
||||
Location: /docs/stories/backlog/STORY-2025-014.md
|
||||
Status: backlog
|
||||
|
||||
Analysis Mode: Objective-focused (improve accessibility)
|
||||
|
||||
Findings:
|
||||
- Priority 1 (Accessibility): 15 issues
|
||||
• 8 missing ARIA attributes
|
||||
• 4 keyboard navigation gaps
|
||||
• 3 screen reader issues
|
||||
- Priority 2 (Critical): 0 issues
|
||||
- Priority 3 (Supporting): 5 improvements
|
||||
|
||||
Files Affected: 6 components
|
||||
Estimated Complexity: Medium
|
||||
|
||||
💡 NEXT STEPS:
|
||||
1. Review story in /docs/stories/backlog/STORY-2025-014.md
|
||||
2. /sdd:story-start STORY-2025-014 # Move to development when ready
|
||||
3. /sdd:project-status # View all stories
|
||||
```
|
||||
|
||||
## Edge Cases
|
||||
|
||||
### No Project Context
|
||||
- DETECT missing `/docs/project-context/` directory
|
||||
- SUGGEST running `/sdd:project-init`
|
||||
- CANNOT proceed without coding standards
|
||||
- EXIT with clear guidance
|
||||
|
||||
### No Code Issues Found
|
||||
- REPORT clean codebase status
|
||||
- SUGGEST code is already well-refactored
|
||||
- OFFER to create story anyway for future improvements
|
||||
- DOCUMENT analysis results even if no issues
|
||||
|
||||
### Framework Not Recognized
|
||||
- DETECT framework from technical-stack.md
|
||||
- FALL BACK to generic code analysis if unknown
|
||||
- WARN that framework-specific patterns unavailable
|
||||
- CONTINUE with structure/naming analysis
|
||||
|
||||
### Conflicting Standards
|
||||
- DETECT contradictions in project context
|
||||
- LOG warnings about conflicts
|
||||
- ASK user to clarify which standard applies
|
||||
- DOCUMENT decision in story
|
||||
|
||||
## Error Handling
|
||||
- **Missing /docs/project-context/**: Exit with suggestion to run `/sdd:project-init`
|
||||
- **No coding-standards.md**: Cannot analyze - critical file missing
|
||||
- **Analysis errors**: Log specific files causing issues, continue with others
|
||||
- **Invalid objective**: Interpret broadly or ask user for clarification
|
||||
|
||||
## Performance Considerations
|
||||
- Code analysis may take 30-60 seconds for large codebases
|
||||
- Show progress indicators during analysis
|
||||
- Cache project context for session
|
||||
- Analyze only relevant files based on objective
|
||||
|
||||
## Related Commands
|
||||
- `/sdd:project-init` - Initialize project structure with standards
|
||||
- `/sdd:project-brief` - Define project goals and constraints
|
||||
- `/sdd:story-new` - Create feature story
|
||||
- `/sdd:story-start [id]` - Begin refactoring work
|
||||
- `/sdd:project-status` - View all stories
|
||||
|
||||
## Constraints
|
||||
- ✅ MUST use DISCOVERED standards (no assumptions)
|
||||
- ✅ MUST include file:line references in findings
|
||||
- ✅ MUST prioritize by objective when provided
|
||||
- ⚠️ NEVER suggest refactoring without evidence
|
||||
- 📋 MUST provide specific, actionable tasks
|
||||
- 🔧 SHOULD include before/after examples
|
||||
- 💾 MUST assess risk for breaking changes
|
||||
- 🧪 MUST verify existing tests will pass
|
||||
Reference in New Issue
Block a user