fix(refactor-plan): expand skill description and instructions

docs/README.skills.md

@@ -305,7 +305,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to
 | [readme-blueprint-generator](../skills/readme-blueprint-generator/SKILL.md)<br />`gh skills install github/awesome-copilot readme-blueprint-generator` | Intelligent README.md generation prompt that analyzes project documentation structure and creates comprehensive repository documentation. Scans .github/copilot directory files and copilot-instructions.md to extract project information, technology stack, architecture, development workflow, coding standards, and testing approaches while generating well-structured markdown documentation with proper formatting, cross-references, and developer-focused content. | None |
 | [refactor](../skills/refactor/SKILL.md)<br />`gh skills install github/awesome-copilot refactor` | Surgical code refactoring to improve maintainability without changing behavior. Covers extracting functions, renaming variables, breaking down god functions, improving type safety, eliminating code smells, and applying design patterns. Less drastic than repo-rebuilder; use for gradual improvements. | None |
 | [refactor-method-complexity-reduce](../skills/refactor-method-complexity-reduce/SKILL.md)<br />`gh skills install github/awesome-copilot refactor-method-complexity-reduce` | Refactor given method `${input:methodName}` to reduce its cognitive complexity to `${input:complexityThreshold}` or below, by extracting helper methods. | None |
-| [refactor-plan](../skills/refactor-plan/SKILL.md)<br />`gh skills install github/awesome-copilot refactor-plan` | Plan a multi-file refactor with proper sequencing and rollback steps | None |
+| [refactor-plan](../skills/refactor-plan/SKILL.md)<br />`gh skills install github/awesome-copilot refactor-plan` | Create a concrete plan before starting a multi-file refactor. Use when the user asks to plan, sequence, scope, or safely execute a refactor across multiple files; always investigate first, output the plan, and wait for confirmation before making code changes. | None |
 | [remember](../skills/remember/SKILL.md)<br />`gh skills install github/awesome-copilot remember` | Transforms lessons learned into domain-organized memory instructions (global or workspace). Syntax: `/remember [>domain [scope]] lesson clue` where scope is `global` (default), `user`, `workspace`, or `ws`. | None |
 | [remember-interactive-programming](../skills/remember-interactive-programming/SKILL.md)<br />`gh skills install github/awesome-copilot remember-interactive-programming` | A micro-prompt that reminds the agent that it is an interactive programmer. Works great in Clojure when Copilot has access to the REPL (probably via Backseat Driver). Will work with any system that has a live REPL that the agent can use. Adapt the prompt with any specific reminders in your workflow and/or workspace. | None |
 | [repo-story-time](../skills/repo-story-time/SKILL.md)<br />`gh skills install github/awesome-copilot repo-story-time` | Generate a comprehensive repository summary and narrative story from commit history | None |

skills/refactor-plan/SKILL.md

@@ -1,23 +1,24 @@
 ---
 name: refactor-plan
-description: 'Plan a multi-file refactor with proper sequencing and rollback steps'
+description: 'Create a concrete plan before starting a multi-file refactor. Use when the user asks to plan, sequence, scope, or safely execute a refactor across multiple files; always investigate first, output the plan, and wait for confirmation before making code changes.'
 ---
 
 # Refactor Plan
 
-Create a detailed plan for this refactoring task.
-
-## Refactor Goal
-
-{{refactor_description}}
+Create a detailed plan before making any code changes.
 
 ## Instructions
 
-1. Search the codebase to understand current state
-2. Identify all affected files and their dependencies
-3. Plan changes in a safe sequence (types first, then implementations, then tests)
-4. Include verification steps between changes
-5. Consider rollback if something fails
+1. Do not edit files while preparing the plan.
+2. Search the codebase to understand the current state. Read enough implementation, tests, configuration, and docs to make the plan specific to the repository.
+3. Identify affected files, ownership boundaries, dependencies, and likely hidden coupling.
+4. Plan changes in a safe sequence. Prefer contracts and types first, then implementations, then callers, then tests, then cleanup.
+5. Include verification steps between phases and a final validation command.
+6. Include rollback or recovery steps for the riskiest phases.
+7. Output the complete plan using the format below.
+8. Stop after the plan and ask for confirmation before implementing. If the user already asked you to implement, still produce the plan first and wait for confirmation unless they explicitly said to continue without review after the plan.
+
+If the request is too ambiguous to plan safely, ask concise clarifying questions instead of editing files.
 
 ## Output Format
 
@@ -62,4 +63,4 @@ If something fails:
 - [Potential issue and mitigation]
 ```
 
-Shall I proceed with Phase 1?
+After the plan, ask: "Shall I proceed with Phase 1?"