ui/.cursor/skills/refactor/phases/02-analysis.md

Phase 2: Analysis & Task Decomposition

Role: Researcher, software architect, and task planner Goal: Research improvements, produce a refactoring roadmap, and decompose into implementable tasks Constraints: Analysis and planning only — no code changes

2a. Deep Research

1. Analyze current implementation patterns
2. Research modern approaches for similar systems
3. Identify what could be done differently
4. Suggest improvements based on state-of-the-art practices

Write RUN_DIR/analysis/research_findings.md:

• Current state analysis: patterns used, strengths, weaknesses
• Alternative approaches per component: current vs alternative, pros/cons, migration effort
• Prioritized recommendations: quick wins + strategic improvements

2b. Solution Assessment & Hardening Tracks

1. Assess current implementation against acceptance criteria
2. Identify weak points in codebase, map to specific code areas
3. Perform gap analysis: acceptance criteria vs current state
4. Prioritize changes by impact and effort

Present optional hardening tracks for user to include in the roadmap:

══════════════════════════════════════
 DECISION REQUIRED: Include hardening tracks?
══════════════════════════════════════
 A) Technical Debt — identify and address design/code/test debt
 B) Performance Optimization — profile, identify bottlenecks, optimize
 C) Security Review — OWASP Top 10, auth, encryption, input validation
 D) All of the above
 E) None — proceed with structural refactoring only
══════════════════════════════════════

For each selected track, add entries to RUN_DIR/list-of-changes.md (append to the file produced in Phase 1):

• Track A: tech debt items with location, impact, effort
• Track B: performance bottlenecks with profiling data
• Track C: security findings with severity and fix description

Write RUN_DIR/analysis/refactoring_roadmap.md:

• Weak points assessment: location, description, impact, proposed solution
• Gap analysis: what's missing, what needs improvement
• Phased roadmap: Phase 1 (critical fixes), Phase 2 (major improvements), Phase 3 (enhancements)
• Selected hardening tracks and their items

2c. Create Epic

Create a work item tracker epic for this refactoring run:

1. Epic name: the RUN_DIR name (e.g., 01-testability-refactoring)
2. Create the epic via configured tracker MCP
3. Record the Epic ID — all tasks in 2d will be linked under this epic
4. If tracker unavailable, use PENDING placeholder and note for later

2d. Task Decomposition

Convert the finalized RUN_DIR/list-of-changes.md into implementable task files.

1. Read RUN_DIR/list-of-changes.md
2. For each change entry (or group of related entries), create an atomic task file in TASKS_DIR:
   • Use the standard task template format (.cursor/skills/decompose/templates/task.md)
   • File naming: [##]_refactor_[short_name].md (temporary numeric prefix)
   • Task: PENDING_refactor_[short_name]
   • Description: derived from the change entry's Problem + Change fields
   • Complexity: estimate 1-5 points; split into multiple tasks if >5
   • Dependencies: map change-level dependencies (C01, C02) to task-level tracker IDs
   • Component: from the change entry's File(s) field
   • Epic: the epic created in 2c
   • Acceptance Criteria: derived from the change entry — verify the problem is resolved
3. Create work item ticket for each task under the epic from 2c
4. Rename each file to [TRACKER-ID]_refactor_[short_name].md after ticket creation
5. Update or append to TASKS_DIR/_dependencies_table.md with the refactoring tasks

Self-verification:

• All acceptance criteria are addressed in gap analysis
• Recommendations are grounded in actual code, not abstract
• Roadmap phases are prioritized by impact
• Epic created and all tasks linked to it
• Every entry in list-of-changes.md has a corresponding task file in TASKS_DIR
• No task exceeds 5 complexity points
• Task dependencies are consistent (no circular dependencies)
• _dependencies_table.md includes all refactoring tasks
• Every task has a work item ticket (or PENDING placeholder)

Save action: Write analysis artifacts to RUN_DIR, task files to TASKS_DIR

BLOCKING: Present refactoring roadmap and task list to user. Do NOT proceed until user confirms.

Quick Assessment mode stops here. Present final summary and write FINAL_report.md with phases 0-2 content.