feature-refactor

You are orchestrating a comprehensive feature refactoring workflow with multi-agent collaboration. Follow this structured process:

Core Principle

⚠️ CRITICAL: Read the code carefully before designing new solutions - the existing implementation often already handles edge cases. Understanding what's already there prevents duplicate solutions and unnecessary complexity.

Phase 0: Feature Understanding (Parallel Analysis)

IMPORTANT: Execute BOTH analyses in PARALLEL (single message with 2 Task tool calls) for maximum efficiency.

Step 0.1: Launch Parallel Understanding Agents

Execute in PARALLEL:

Analysis 1: Code Exploration (code-explorer)

Use the Task tool with subagent_type=code-explorer to deeply understand the existing feature: $ARGUMENTS

The code-explorer should:

• Find ALL files related to this feature (entry points, core logic, utilities, tests)
• Trace execution paths from entry to data storage
• Map architecture layers (presentation, business logic, data)
• Identify design patterns and abstractions currently in use
• Document all dependencies (internal and external)
• Find integration points with other features
• Note any technical debt or improvement areas
• List ALL essential files for understanding this feature

Analysis 2: Documentation Review (code-consolidator)

Use the Task tool with subagent_type=code-consolidator to find and analyze documentation for: $ARGUMENTS

The code-consolidator should:

• Search /docs for any documentation about this feature
• Identify documentation location(s) if exists
• Read and summarize existing documentation
• Note any gaps in documentation
• Identify related documentation that might need updates
• Check if documentation matches current implementation
• Flag any outdated or incorrect documentation

Step 0.2: Create Understanding Report

After BOTH agents complete, synthesize findings:

Create: .claude/specs/refactor-{feature-name}/01-understanding.md

# Feature Understanding: {feature-name}

**Analysis Date**: {date}
**Refactor Request**: {$ARGUMENTS}

## Code Analysis (code-explorer findings)

### Feature Entry Points
- [Entry point 1: file:line]
- [Entry point 2: file:line]
- ...

### Core Implementation
- [Core file 1: purpose and responsibilities]
- [Core file 2: purpose and responsibilities]
- ...

### Architecture Layers
- **Presentation Layer**: [files and responsibilities]
- **Business Logic Layer**: [files and responsibilities]
- **Data Layer**: [files and responsibilities]

### Design Patterns Used
- [Pattern 1: where and how it's used]
- [Pattern 2: where and how it's used]
- ...

### Dependencies
- **Internal**: [other features this depends on]
- **External**: [libraries, frameworks, APIs]

### Integration Points
- [Feature 1: how they integrate]
- [Feature 2: how they integrate]
- ...

### Technical Debt / Issues
- [Issue 1: description and location]
- [Issue 2: description and location]
- ...

### Essential Files
[Complete list with brief descriptions]

## Documentation Analysis (code-consolidator findings)

### Existing Documentation
- **Location**: [file path(s) in /docs]
- **Content Summary**: [what's documented]
- **Last Updated**: [if available]

### Documentation Gaps
- [Gap 1: what's not documented]
- [Gap 2: what's missing]
- ...

### Outdated Information
- [Outdated 1: what needs updating]
- [Outdated 2: discrepancy with code]
- ...

### Related Documentation
- [Related doc 1: why it's relevant]
- [Related doc 2: connection to this feature]
- ...

## Understanding Summary

### What This Feature Does
[Clear description of feature's purpose and behavior]

### How It Works
[High-level explanation of implementation approach]

### Current State Assessment
- **Code Quality**: [assessment]
- **Documentation Quality**: [assessment]
- **Maintainability**: [assessment]
- **Technical Debt Level**: [assessment]