detections-semantic/.cursor/skills/refactor/SKILL.md

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

name	description	category	tags	disable-model-invocation
refactor	Structured refactoring workflow (6-phase method) with three execution modes: - Full Refactoring: all 6 phases — baseline, discovery, analysis, safety net, execution, hardening - Targeted Refactoring: skip discovery if docs exist, focus on a specific component/area - Quick Assessment: phases 0-2 only, outputs a refactoring plan without execution Supports project mode (_docs/ structure) and standalone mode (@file.md). Trigger phrases: - "refactor", "refactoring", "improve code" - "analyze coupling", "decoupling", "technical debt" - "refactoring assessment", "code quality improvement"	evolve	refactoring coupling technical-debt performance hardening	true

Structured Refactoring (6-Phase Method)

Transform existing codebases through a systematic refactoring workflow: capture baseline, document current state, research improvements, build safety net, execute changes, and harden.

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; never accumulate unsaved work
• Ask, don't assume: when scope or priorities are unclear, STOP and ask the user

Context Resolution

Determine the operating mode based on invocation before any other logic runs.

Project mode (no explicit input file provided):

• PROBLEM_DIR: _docs/00_problem/
• SOLUTION_DIR: _docs/01_solution/
• COMPONENTS_DIR: _docs/02_components/
• TESTS_DIR: _docs/02_tests/
• REFACTOR_DIR: _docs/04_refactoring/
• All existing guardrails apply.

Standalone mode (explicit input file provided, e.g. /refactor @some_component.md):

• INPUT_FILE: the provided file (treated as component/area description)
• REFACTOR_DIR: _standalone/refactoring/
• Guardrails relaxed: only INPUT_FILE must exist and be non-empty
• acceptance_criteria.md is optional — warn if absent

Announce the detected mode and resolved paths to the user before proceeding.

Mode Detection

After context resolution, determine the execution mode:

1. User explicitly says "quick assessment" or "just assess" → Quick Assessment
2. User explicitly says "refactor [component/file/area]" with a specific target → Targeted Refactoring
3. Default → Full Refactoring

Mode	Phases Executed	When to Use
Full Refactoring	0 → 1 → 2 → 3 → 4 → 5	Complete refactoring of a system or major area
Targeted Refactoring	0 → (skip 1 if docs exist) → 2 → 3 → 4 → 5	Refactor a specific component; docs already exist
Quick Assessment	0 → 1 → 2	Produce a refactoring roadmap without executing changes

Inform the user which mode was detected and confirm before proceeding.

Prerequisite Checks (BLOCKING)

Project mode:

1. PROBLEM_DIR exists with problem.md (or problem_description.md) — STOP if missing, ask user to create it
2. If acceptance_criteria.md is missing: warn and ask whether to proceed
3. Create REFACTOR_DIR if it does not exist
4. If REFACTOR_DIR already contains artifacts, ask user: resume from last checkpoint or start fresh?

Standalone mode:

1. INPUT_FILE exists and is non-empty — STOP if missing
2. Warn if no acceptance_criteria.md provided
3. Create REFACTOR_DIR if it does not exist

Artifact Management

Directory Structure

REFACTOR_DIR/
├── baseline_metrics.md          (Phase 0)
├── discovery/
│   ├── components/
│   │   └── [##]_[name].md       (Phase 1)
│   ├── solution.md              (Phase 1)
│   └── system_flows.md          (Phase 1)
├── analysis/
│   ├── research_findings.md     (Phase 2)
│   └── 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.md        (Phase 5)
│   ├── performance.md           (Phase 5)
│   └── security.md              (Phase 5)
└── FINAL_report.md              (after all phases)

Save Timing

Phase	Save immediately after	Filename
Phase 0	Baseline captured	baseline_metrics.md
Phase 1	Each component documented	discovery/components/[##]_[name].md
Phase 1	Solution synthesized	discovery/solution.md, discovery/system_flows.md
Phase 2	Research complete	analysis/research_findings.md
Phase 2	Roadmap produced	analysis/refactoring_roadmap.md
Phase 3	Test specs written	test_specs/[##]_[test_name].md
Phase 4	Coupling analyzed	coupling_analysis.md
Phase 4	Execution complete	execution_log.md
Phase 5	Each hardening track	hardening/<track>.md
Final	All phases done	FINAL_report.md

Resumability

If REFACTOR_DIR already contains artifacts:

1. List existing files and match to the save timing table
2. Identify the last completed phase based on which artifacts exist
3. Resume from the next incomplete phase
4. Inform the user which phases are being skipped

Progress Tracking

At the start of execution, create a TodoWrite with all applicable phases. Update status as each phase completes.

Workflow

Phase 0: Context & Baseline

Role: Software engineer preparing for refactoring Goal: Collect refactoring goals and capture baseline metrics Constraints: Measurement only — no code changes

0a. Collect Goals

If PROBLEM_DIR files do not yet exist, help the user create them:

1. problem.md — what the system currently does, what changes are needed, pain points
2. acceptance_criteria.md — success criteria for the refactoring
3. security_approach.md — security requirements (if applicable)

Store in PROBLEM_DIR.

0b. Capture Baseline

1. Read problem description and acceptance criteria
2. Measure current system metrics using project-appropriate tools:

Metric Category	What to Capture
Coverage	Overall, unit, integration, critical paths
Complexity	Cyclomatic complexity (avg + top 5 functions), LOC, tech debt ratio
Code Smells	Total, critical, major
Performance	Response times (P50/P95/P99), CPU/memory, throughput
Dependencies	Total count, outdated, security vulnerabilities
Build	Build time, test execution time, deployment time

3. Create functionality inventory: all features/endpoints with status and coverage

Self-verification:

• All metric categories measured (or noted as N/A with reason)
• Functionality inventory is complete
• Measurements are reproducible

Save action: Write REFACTOR_DIR/baseline_metrics.md

BLOCKING: Present baseline summary to user. Do NOT proceed until user confirms.

---

Phase 1: Discovery

Role: Principal software architect Goal: Generate documentation from existing code and form solution description Constraints: Document what exists, not what should be. No code changes.

Skip condition (Targeted mode): If COMPONENTS_DIR and SOLUTION_DIR already contain documentation for the target area, skip to Phase 2. Ask user to confirm skip.

1a. Document Components

For each component in the codebase:

1. Analyze project structure, directories, files
2. Go file by file, analyze each method
3. Analyze connections between components

Write per component to REFACTOR_DIR/discovery/components/[##]_[name].md:

• Purpose and architectural patterns
• Mermaid diagrams for logic flows
• API reference table (name, description, input, output)
• Implementation details: algorithmic complexity, state management, dependencies
• Caveats, edge cases, known limitations

1b. Synthesize Solution & Flows

1. Review all generated component documentation
2. Synthesize into a cohesive solution description
3. Create flow diagrams showing component interactions

Write:

• REFACTOR_DIR/discovery/solution.md — product description, component overview, interaction diagram
• REFACTOR_DIR/discovery/system_flows.md — Mermaid flowcharts per major use case

Also copy to project standard locations if in project mode:

• SOLUTION_DIR/solution.md
• COMPONENTS_DIR/system_flows.md

Self-verification:

• Every component in the codebase is documented
• Solution description covers all components
• Flow diagrams cover all major use cases
• Mermaid diagrams are syntactically correct

Save action: Write discovery artifacts

BLOCKING: Present discovery summary to user. Do NOT proceed until user confirms documentation accuracy.

---

Phase 2: Analysis

Role: Researcher and software architect Goal: Research improvements and produce a refactoring roadmap Constraints: Analysis 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 REFACTOR_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

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

Write REFACTOR_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)

Self-verification:

• All acceptance criteria are addressed in gap analysis
• Recommendations are grounded in actual code, not abstract
• Roadmap phases are prioritized by impact
• Quick wins are identified separately

Save action: Write analysis artifacts

BLOCKING: Present refactoring roadmap 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.

---

Phase 3: Safety Net

Role: QA engineer and developer Goal: Design and implement tests that capture current behavior before refactoring Constraints: Tests must all pass on the current codebase before proceeding

3a. Design Test Specs

Coverage requirements (must meet before refactoring):

• Minimum overall coverage: 75%
• Critical path coverage: 90%
• All public APIs must have integration tests
• All error handling paths must be tested

For each critical area, write test specs to REFACTOR_DIR/test_specs/[##]_[test_name].md:

• Integration tests: summary, current behavior, input data, expected result, max expected time
• Acceptance tests: summary, preconditions, steps with expected results
• Coverage analysis: current %, target %, uncovered critical paths

3b. Implement Tests

1. Set up test environment and infrastructure if not exists
2. Implement each test from specs
3. Run tests, verify all pass on current codebase
4. Document any discovered issues

Self-verification:

• Coverage requirements met (75% overall, 90% critical paths)
• All tests pass on current codebase
• All public APIs have integration tests
• Test data fixtures are configured

Save action: Write test specs; implemented tests go into the project's test folder

GATE (BLOCKING): ALL tests must pass before proceeding to Phase 4. If tests fail, fix the tests (not the code) or ask user for guidance. Do NOT proceed to Phase 4 with failing tests.

---

Phase 4: Execution

Role: Software architect and developer Goal: Analyze coupling and execute decoupling changes Constraints: Small incremental changes; tests must stay green after every change

4a. Analyze Coupling

1. Analyze coupling between components/modules
2. Map dependencies (direct and transitive)
3. Identify circular dependencies
4. Form decoupling strategy

Write REFACTOR_DIR/coupling_analysis.md:

• Dependency graph (Mermaid)
• Coupling metrics per component
• Problem areas: components involved, coupling type, severity, impact
• Decoupling strategy: priority order, proposed interfaces/abstractions, effort estimates

BLOCKING: Present coupling analysis to user. Do NOT proceed until user confirms strategy.

4b. Execute Decoupling

For each change in the decoupling strategy:

1. Implement the change
2. Run integration tests
3. Fix any failures
4. Commit with descriptive message

Address code smells encountered: long methods, large classes, duplicate code, dead code, magic numbers.

Write REFACTOR_DIR/execution_log.md:

• Change description, files affected, test status per change
• Before/after metrics comparison against baseline

Self-verification:

• All tests still pass after execution
• No circular dependencies remain (or reduced per plan)
• Code smells addressed
• Metrics improved compared to baseline

Save action: Write execution artifacts

BLOCKING: Present execution summary to user. Do NOT proceed until user confirms.

---

Phase 5: Hardening (Optional, Parallel Tracks)

Role: Varies per track Goal: Address technical debt, performance, and security Constraints: Each track is optional; user picks which to run

Present the three tracks and let user choose which to execute:

Track A: Technical Debt

Role: Technical debt analyst

1. Identify and categorize debt items: design, code, test, documentation
2. Assess each: location, description, impact, effort, interest (cost of not fixing)
3. Prioritize: quick wins → strategic debt → tolerable debt
4. Create actionable plan with prevention measures

Write REFACTOR_DIR/hardening/technical_debt.md

Track B: Performance Optimization

Role: Performance engineer

1. Profile current performance, identify bottlenecks
2. For each bottleneck: location, symptom, root cause, impact
3. Propose optimizations with expected improvement and risk
4. Implement one at a time, benchmark after each change
5. Verify tests still pass

Write REFACTOR_DIR/hardening/performance.md with before/after benchmarks

Track C: Security Review

Role: Security engineer

1. Review code against OWASP Top 10
2. Verify security requirements from security_approach.md are met
3. Check: authentication, authorization, input validation, output encoding, encryption, logging

Write REFACTOR_DIR/hardening/security.md:

• Vulnerability assessment: location, type, severity, exploit scenario, fix
• Security controls review
• Compliance check against security_approach.md
• Recommendations: critical fixes, improvements, hardening

Self-verification (per track):

• All findings are grounded in actual code
• Recommendations are actionable with effort estimates
• All tests still pass after any changes

Save action: Write hardening artifacts

---

Final Report

After all executed phases complete, write REFACTOR_DIR/FINAL_report.md:

• Refactoring mode used and phases executed
• Baseline metrics vs final metrics comparison
• Changes made summary
• Remaining items (deferred to future)
• Lessons learned

Escalation Rules

Situation	Action
Unclear refactoring scope	ASK user
Ambiguous acceptance criteria	ASK user
Tests failing before refactoring	ASK user — fix tests or fix code?
Coupling change risks breaking external contracts	ASK user
Performance optimization vs readability trade-off	ASK user
Missing baseline metrics (no test suite, no CI)	WARN user, suggest building safety net first
Security vulnerability found during refactoring	WARN user immediately, don't defer

Trigger Conditions

When the user wants to:

• Improve existing code structure or quality
• Reduce technical debt or coupling
• Prepare codebase for new features
• Assess code health before major changes

Keywords: "refactor", "refactoring", "improve code", "reduce coupling", "technical debt", "code quality", "decoupling"

Methodology Quick Reference

┌────────────────────────────────────────────────────────────────┐
│           Structured Refactoring (6-Phase Method)              │
├────────────────────────────────────────────────────────────────┤
│ CONTEXT: Resolve mode (project vs standalone) + set paths      │
│ MODE: Full / Targeted / Quick Assessment                       │
│                                                                │
│ 0. Context & Baseline  → baseline_metrics.md                   │
│    [BLOCKING: user confirms baseline]                          │
│ 1. Discovery           → discovery/ (components, solution)     │
│    [BLOCKING: user confirms documentation]                     │
│ 2. Analysis            → analysis/ (research, roadmap)         │
│    [BLOCKING: user confirms roadmap]                           │
│    ── Quick Assessment stops here ──                           │
│ 3. Safety Net          → test_specs/ + implemented tests       │
│    [GATE: all tests must pass]                                 │
│ 4. Execution           → coupling_analysis, execution_log      │
│    [BLOCKING: user confirms changes]                           │
│ 5. Hardening           → hardening/ (debt, perf, security)     │
│    [optional, user picks tracks]                               │
│    ─────────────────────────────────────────────────           │
│    FINAL_report.md                                             │
├────────────────────────────────────────────────────────────────┤
│ Principles: Preserve behavior · Measure before/after           │
│             Small changes · Save immediately · Ask don't assume│
└────────────────────────────────────────────────────────────────┘