1# Phase 2: Generate Upgrade Plan
2 
3Load this file when executing Phase 2. Refer back to [`upgrade-success-criteria`](../rules/upgrade-success-criteria.md) and [`upgrade-strategy`](../rules/upgrade-strategy.md) for success criteria and strategy, and [`../rules/troubleshooting.md`](../rules/troubleshooting.md) when failures occur.
4 
5## 1. Initialize
6 
71. Update `plan.md`: replace all remaining placeholders
82. Extract user-specified guidelines from prompt into "Guidelines" section (bulleted list; leave empty if none)
9 
10## 2. Environment Analysis
11 
121. Read HTML comments in "Available Tools" section of `plan.md` to understand rules and expected format
132. Record discovered JDK versions and paths
143. Detect wrapper presence; if wrapper exists, read wrapper properties to determine build tool version
154. Check build tool version compatibility with JDK — flag incompatible versions for upgrade
16 
17## 3. Dependency Analysis
18 
191. Read HTML comments in "Technology Stack" and "Derived Upgrades" sections of `plan.md` to understand rules and expected format
202. Identify core tech stack across **ALL modules** (direct deps + upgrade-critical deps)
213. Include build tool (Maven/Gradle) and build plugins (`maven-compiler-plugin`, `maven-surefire-plugin`, etc.) in the technology stack analysis
224. Flag EOL dependencies (high priority for upgrade)
235. Consult the Migration Guidelines for package mappings and migration guides
246. Populate "Technology Stack" and "Derived Upgrades"
25 
26## 4. Upgrade Path Design
27 
281. Read HTML comments in "Key Challenges" and "Upgrade Steps" sections of `plan.md` to understand rules and expected format
292. For incompatible deps, prefer: Replacement > Adaptation > Rewrite
303. Finalize "Available Tools" section based on the planned step sequence
314. Design step sequence:
32   - **Step 1 (MANDATORY)**: Setup Baseline — run compile/test with current JDK, document results
33   - **Steps 2-N**: Upgrade steps — dependency order, high-risk early, isolated breaking changes. Compilation must pass (both main and test code); test failures documented for Final Validation.
34   - **Final step (MANDATORY)**: Final Validation — verify all goals met, all TODOs resolved, achieve **Upgrade Success Criteria** through iterative test & fix loop.
355. Identify high-risk areas for "Key Challenges" section
366. Write steps following format in `plan.md`
37 
38## 5. Plan Review
39 
401. Verify all placeholders filled in `plan.md`, check for missing coverage/infeasibility/limitations
412. Revise plan as needed for completeness and feasibility; document unfixable limitations in "Plan Review" section
423. Ensure all sections of `plan.md` are fully populated (per **Template compliance** rule) and all HTML comments removed
43 
44After plan generation, proceed directly to execution — create `.github/java-upgrade/{RUN_ID}/progress.md` from the Progress Template, replace placeholders, and begin execution. Log the migration plan, then proceed without pausing for confirmation.
45