# 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.