ai-training/.cursor/skills/refactor/SKILL.md

name, description, category, tags, trigger_phrases, disable-model-invocation

name	description	category	tags	trigger_phrases	disable-model-invocation
refactor	Structured 9-phase refactoring workflow with three execution modes: Full (all phases), Targeted (skip discovery), Quick Assessment (phases 0-2 only). Supports project mode (_docs/) and standalone mode (@file.md).	evolve	refactoring coupling technical-debt performance hardening	refactor refactoring improve code analyze coupling decoupling technical debt code quality	true

Structured Refactoring

Phase details live in phases/ — read the relevant file before executing each phase.

Core Principles

• Preserve behavior first: never refactor without a passing test suite
• Measure before and after: every change must be justified by metrics
• Small incremental changes: commit frequently, never break tests
• Save immediately: write artifacts to disk after each phase
• Ask, don't assume: when scope or priorities are unclear, STOP and ask the user

Context Resolution

Determine operating mode before any other logic runs. Announce detected mode and paths to user.

	Project mode (default)	Standalone mode (/refactor @file.md)
PROBLEM_DIR	_docs/00_problem/	N/A
SOLUTION_DIR	_docs/01_solution/	N/A
COMPONENTS_DIR	_docs/02_document/components/	N/A
DOCUMENT_DIR	_docs/02_document/	N/A
REFACTOR_DIR	_docs/04_refactoring/	_standalone/refactoring/
Prereqs	problem.md required, acceptance_criteria.md warn if absent	INPUT_FILE must exist and be non-empty

Create REFACTOR_DIR if missing. If it already has artifacts, ask user: resume or start fresh?

Workflow

Phase	File	Summary	Gate
0	phases/00-baseline.md	Collect goals, capture baseline metrics	BLOCKING: user confirms
1	phases/01-discovery.md	Document components, synthesize solution	BLOCKING: user confirms
2	phases/02-analysis.md	Research improvements, produce roadmap	BLOCKING: user confirms
		Quick Assessment stops here
3	phases/03-safety-net.md	Design and implement pre-refactoring tests	GATE: all tests pass
4	phases/04-execution.md	Analyze coupling, execute decoupling	BLOCKING: user confirms
5	phases/05-hardening.md	Technical debt, performance, security	Optional: user picks tracks
6	phases/06-test-sync.md	Remove obsolete, update broken, add new tests	GATE: all tests pass
7	phases/07-verification.md	Run full suite, compare metrics vs baseline	GATE: all pass, no regressions
8	phases/08-documentation.md	Update _docs/ to reflect refactored state	Skip in standalone mode

Mode detection:

• "quick assessment" / "just assess" → phases 0–2
• "refactor [specific target]" → skip phase 1 if docs exist
• Default → all phases

At the start of execution, create a TodoWrite with all applicable phases.

Artifact Structure

All artifacts are written to REFACTOR_DIR:

baseline_metrics.md                      Phase 0
discovery/components/[##]_[name].md      Phase 1
discovery/solution.md                    Phase 1
discovery/system_flows.md                Phase 1
analysis/research_findings.md            Phase 2
analysis/refactoring_roadmap.md          Phase 2
test_specs/[##]_[test_name].md           Phase 3
coupling_analysis.md                     Phase 4
execution_log.md                         Phase 4
hardening/{technical_debt,performance,security}.md   Phase 5
test_sync/{obsolete_tests,updated_tests,new_tests}.md  Phase 6
verification_report.md                   Phase 7
doc_update_log.md                        Phase 8
FINAL_report.md                          after all phases

Resumability: match existing artifacts to phases above, resume from next incomplete phase.

Final Report

After all phases complete, write REFACTOR_DIR/FINAL_report.md: mode used, phases executed, baseline vs final metrics, changes summary, remaining items, lessons learned.

Escalation Rules

Situation	Action
Unclear scope or ambiguous criteria	ASK user
Tests failing before refactoring	ASK user — fix tests or fix code?
Risk of breaking external contracts	ASK user
Performance vs readability trade-off	ASK user
No test suite or CI exists	WARN user, suggest safety net first
Security vulnerability found	WARN user immediately