missions/.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. Extract the Project Constraint Matrix from problem.md, restrictions.md, acceptance_criteria.md, current architecture/docs, and actual code constraints. Include required inputs/outputs, operating context, lifecycle assumptions, integration boundaries, non-functional targets, and hard disqualifiers.
3. Research modern approaches for similar systems
4. For each alternative pattern/library/service/architecture/algorithm, research intrinsic implementation constraints: required inputs/outputs, runtime assumptions, supported deployment modes, resource needs, operational limits, licensing/security constraints, and known failure reports.
5. Identify what could be done differently
6. Suggest improvements only when they fit the Project Constraint Matrix. A cleaner or more modern approach that violates product constraints must be marked Rejected or Experimental only, not added as a roadmap recommendation.

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
• Constraint-fit table: recommendation, constraints checked, evidence, mismatches/disqualifiers, status (Selected / Rejected / Experimental only / Needs user decision)

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
5. Reject or escalate any proposed refactor that improves code structure while weakening required behavior, integration contracts, runtime constraints, safety/security posture, or acceptance criteria

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
• Applicability gate: each roadmap item must state constraint fit, mismatches, required evidence, and status (Selected / Rejected / Experimental only / Needs user decision)

BLOCKING applicability gate: Before 2c and 2d, every recommendation in the roadmap must be Selected. Items marked Rejected are excluded. Items marked Experimental only or Needs user decision require a user decision before task creation.

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
• Every recommendation has been checked against the Project Constraint Matrix
• No recommendation violates product restrictions, acceptance criteria, documented architecture decisions, or actual code integration boundaries
• Rejected and experimental approaches are documented but not converted into implementation tasks without user approval
• 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.