/sdd:story-refactor

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-init first
- EXIT with initialization guidance
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

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

/story-refactor