14 KiB
14 KiB
/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
- CHECK if
/docs/project-context/directory exists - IF missing:
- SUGGEST running
/sdd:project-initfirst - EXIT with initialization guidance
- SUGGEST running
- 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
- PARSE optional objective parameter
- IF no objective provided:
- SET analysis mode = comprehensive
- ANALYZE all code quality dimensions
- 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
- MAP objective to analysis focus areas:
Phase 3: Code Analysis
-
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
-
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
- GENERATE story ID in format
STORY-YYYY-NNN:- YYYY = current year
- NNN = next available number
- CHECK for existing IDs across all story directories
- ENSURE uniqueness
Phase 5: Story File Creation
-
ENSURE
/docs/stories/backlog/directory exists -
CREATE story file at
/docs/stories/backlog/[story-id].md -
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)
-
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
-
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] -
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
# [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
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
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
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