455 lines
14 KiB
Markdown
455 lines
14 KiB
Markdown
# /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 |