Claude-Code-Workflow/.claude/commands/workflow/refactor-cycle.md

name, description, argument-hint, allowed-tools

name	description	argument-hint	allowed-tools
refactor-cycle	Tech debt discovery and self-iterating refactoring with multi-dimensional analysis, prioritized execution, regression validation, and reflection-driven adjustment	[-y|--yes] [-c|--continue] [--scope=module|project] "module or refactoring goal"	TodoWrite(*), Task(*), AskUserQuestion(*), Read(*), Grep(*), Glob(*), Bash(*), Edit(*), Write(*)

Auto Mode

When --yes or -y: Auto-confirm prioritization, use recommended refactoring strategy, skip interactive checkpoints.

Workflow Refactor-Cycle Command

Quick Start

# Discover and fix tech debt in a module
/workflow:refactor-cycle "src/auth 模块的技术债务清理"

# Auto mode - fully autonomous
/workflow:refactor-cycle -y "支付服务重构优化"

# Project-wide scan
/workflow:refactor-cycle --scope=project "全项目技术债务扫描与重构"

# Continue interrupted session
/workflow:refactor-cycle --continue "认证模块"

Context Source: cli-explore-agent + Gemini/Codex multi-dimensional analysis Output Directory: .workflow/.refactor/{session-id}/ Core Innovation: Debt-driven refactoring with regression-safe iterative execution and reflection

What & Why

Core Concept

Closed-loop tech debt lifecycle: Discover → Assess → Plan → Refactor → Validate → Reflect → Next — each refactoring item is executed, validated against regression, and reflected upon before proceeding.

vs Existing Commands:

• workflow:lite-fix: Single bug fix, no systematic debt analysis
• workflow:plan + execute: Generic implementation, no debt-aware prioritization or regression validation
• This command: Full debt lifecycle — discovery through multi-dimensional scan, prioritized execution with per-item regression validation

Value Proposition

1. Systematic Discovery: Multi-dimensional scan (code quality, architecture, dependencies, test gaps, performance)
2. Risk-Aware Prioritization: Impact × effort matrix with dependency-aware ordering
3. Regression-Safe: Each refactoring item validated before proceeding to next
4. Documented Reasoning: Every debt item, prioritization decision, and refactoring outcome recorded

Output Artifacts

2 core files + 1 trace directory:

Artifact	Type	Description
reflection-log.md	Human-readable	⭐ Debt inventory, prioritization rationale, per-item refactoring reflections, conclusions
state.json	Machine-readable	Debt items, priority queue, refactoring plans, validation results, iteration state
.trace/	Raw logs	CLI analysis outputs, test outputs, diagnostics snapshots

.workflow/.refactor/RFT-{slug}-{date}/
├── reflection-log.md    # ⭐ Debt discovery + prioritization + per-item reflections + conclusions
├── state.json           # Debt inventory + queue + plans + validation + iteration state
└── .trace/              # Raw logs (CLI outputs, test results, diagnostics)
    ├── discovery-cli.txt
    ├── item-{N}-cli.txt
    └── test-output.log

Overview

┌─────────────────────────────────────────────────────────────────────────┐
│              TECH DEBT REFACTORING CYCLE                                 │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  Phase 1: Session Initialization                                         │
│     ├─ Parse input (module/goal)                                         │
│     ├─ Create session directory                                          │
│     └─ Initialize reflection-log.md + state.json                         │
│                                                                          │
│  Phase 2: Debt Discovery                                                 │
│     ├─ cli-explore-agent: Codebase structure & patterns                 │
│     ├─ CLI multi-dimensional scan:                                       │
│     │   ├─ Code quality (complexity, duplication, dead code)            │
│     │   ├─ Architecture (coupling, cohesion, layering violations)       │
│     │   ├─ Dependencies (outdated, circular, unused)                    │
│     │   ├─ Test gaps (untested paths, fragile tests)                    │
│     │   └─ Maintainability (naming, documentation, type safety)        │
│     ├─ Build debt inventory → state.json.debt_items                     │
│     └─ Append findings to reflection-log.md                              │
│                                                                          │
│  Phase 3: Assessment & Prioritization                                    │
│     ├─ Score each item: impact (1-5) × effort (1-5)                    │
│     ├─ Analyze dependency ordering (what must refactor first)           │
│     ├─ [Interactive] User confirms/adjusts priorities                   │
│     ├─ Build execution queue → state.json.queue                         │
│     └─ Append prioritization rationale to reflection-log.md              │
│                                                                          │
│  Phase 4: Iterative Refactoring Cycle ◄─── CORE LOOP ──┐              │
│     │  For each item in queue:                           │              │
│     ├─ Snapshot: Capture baseline (diagnostics + tests)  │              │
│     ├─ Refactor: @code-developer applies changes         │              │
│     ├─ Validate:                                         │              │
│     │   ├─ Tests pass? (no regression)                   │              │
│     │   ├─ Diagnostics clean? (no new errors)            │              │
│     │   └─ Quality improved? (metrics comparison)        │              │
│     ├─ Decision:                                         │              │
│     │   ├─ PASS → Commit, reflect, next item             │              │
│     │   ├─ PARTIAL → Fix issues, re-validate ───────────→│              │
│     │   └─ FAIL → Rollback, reflect, skip/retry          │              │
│     ├─ Reflect: Record what changed, what broke, why     │              │
│     └─ Commit: git add + commit per completed item       │              │
│                                                                          │
│  Phase 5: Completion                                                     │
│     ├─ Final metrics comparison (before vs after)                       │
│     ├─ Finalize reflection-log.md with conclusions                       │
│     └─ Offer next steps                                                  │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

Implementation

Session Initialization

Objective: Create session context and initialize 2 core files.

Required Actions:

1. Extract module/goal from $ARGUMENTS
2. Generate session ID: RFT-{slug}-{date}
   • slug: lowercase, alphanumeric + Chinese, max 40 chars
   • date: YYYY-MM-DD (UTC+8)
3. Session folder: .workflow/.refactor/{session-id}
4. Parse options:
   • -c / --continue: Resume existing session
   • -y / --yes: Auto-approval mode
   • --scope=module|project (default: module)
5. Auto-detect: If session folder + reflection-log.md exist → continue mode
6. Create: {sessionFolder}/, {sessionFolder}/.trace/

Initialize reflection-log.md:

# Tech Debt Refactoring Log

## Session: {sessionId}
- **Target**: {module_or_goal}
- **Scope**: {module|project}
- **Started**: {timestamp}

---

## Phase 2: Debt Discovery
> Pending...

## Phase 3: Prioritization
> Pending...

## Refactoring Timeline
> Per-item reflections will be appended here...

## Cumulative Learnings
> (Replaced and updated after each refactoring item — not appended)

## Conclusions
> Final synthesis after completion...

Initialize state.json:

{
  "session_id": "RFT-xxx",
  "target": "module or goal",
  "scope": "module|project",
  "started": "timestamp",
  "phase": "init",

  "exploration": null,
  "debt_items": [],
  "queue": [],
  "current_item": null,
  "completed_items": [],
  "skipped_items": [],
  "baseline": null,
  "summary": null
}

---

Phase 2: Debt Discovery

Objective: Systematically scan the codebase and build a debt inventory across multiple dimensions.

Workflow Steps:

1. Codebase Exploration via cli-explore-agent

Task({
  subagent_type: "cli-explore-agent",
  run_in_background: false,
  description: `Explore codebase for debt: ${topicSlug}`,
  prompt: `
## Analysis Context
Target: ${module_or_goal}
Scope: ${scope}
Session: ${sessionFolder}

## MANDATORY FIRST STEPS
1. Run: ccw tool exec get_modules_by_depth '{}'
2. Read: .workflow/project-tech.json (if exists)
3. Search for: complex functions, long files, TODO/FIXME/HACK comments, suppression patterns (@ts-ignore, eslint-disable)

## Exploration Focus
- **Module Structure**: File organization, module boundaries, public APIs
- **Code Metrics**: Longest files, deepest nesting, most complex functions
- **Dependency Graph**: Import chains, circular dependencies, external deps
- **Test Coverage**: Test file mapping, untested modules
- **Pattern Violations**: Inconsistent naming, mixed paradigms, dead exports

## Output
Update state.json field "exploration" with:
{
  "structure": { "files": [], "modules": [], "total_loc": 0 },
  "metrics": { "largest_files": [], "most_complex": [], "deepest_nesting": [] },
  "dependency_issues": { "circular": [], "unused_imports": [], "outdated_deps": [] },
  "test_mapping": { "tested": [], "untested": [], "coverage_estimate": "" },
  "pattern_violations": { "suppressions": [], "todos": [], "inconsistencies": [] },
  "_metadata": { "files_analyzed": 0, "timestamp": "" }
}
Also set state.json "phase" to "explored".
`
})

2. Multi-Dimensional CLI Debt Scan

Bash({
  command: `ccw cli -p "
PURPOSE: Comprehensive tech debt analysis for '${module_or_goal}'
Success: Actionable debt inventory with concrete file:line references

EXPLORATION CONTEXT:
${JSON.stringify(state.exploration, null, 2)}

TASK:
• **Code Quality**: Identify high-complexity functions (cyclomatic >10), duplicated logic (>20 lines), dead code (unreachable/unused exports), overly long files (>500 lines)
• **Architecture**: Detect tight coupling (>5 imports from one module), layering violations (UI→DB direct), god classes/modules, missing abstractions
• **Dependencies**: Flag circular imports, unused dependencies, outdated packages with known vulnerabilities
• **Test Gaps**: Untested critical paths, fragile tests (mock-heavy, timing-dependent), missing edge case coverage
• **Maintainability**: Inconsistent naming conventions, missing types (any/unknown abuse), misleading comments, magic numbers/strings

For each debt item provide:
- id: D-{NNN}
- dimension: code_quality|architecture|dependencies|test_gaps|maintainability
- title: Short description
- location: file:line or module path
- severity: critical|high|medium|low
- description: What's wrong and why it matters
- suggested_fix: How to address it

MODE: analysis
CONTEXT: @**/*
EXPECTED: JSON array of debt items with all fields populated, severity distribution, dimension summary
CONSTRAINTS: Focus on ${scope === 'project' ? 'project-wide patterns' : 'target module and direct dependencies'}
" --tool gemini --mode analysis --rule analysis-review-code-quality`,
  run_in_background: true
})

3. Build debt inventory — parse CLI output, write state.json.debt_items:

[
  {
    "id": "D-001",
    "dimension": "architecture",
    "title": "Circular dependency between auth and user modules",
    "location": "src/auth/index.ts ↔ src/user/index.ts",
    "severity": "high",
    "description": "Bidirectional import creates tight coupling",
    "suggested_fix": "Extract shared types to common module",
    "impact": 0,
    "effort": 0,
    "priority_score": 0,
    "status": "discovered",
    "refactor_plan": null,
    "validation_result": null
  }
]

Save CLI output to .trace/discovery-cli.txt.

4. Append to reflection-log.md (replace ## Phase 2: Debt Discovery placeholder):

## Phase 2: Debt Discovery - {timestamp}

### Scan Summary
- **Total Items Found**: {N}
- **By Dimension**: Code Quality ({N}), Architecture ({N}), Dependencies ({N}), Test Gaps ({N}), Maintainability ({N})
- **By Severity**: Critical ({N}), High ({N}), Medium ({N}), Low ({N})

### Key Findings
- {top finding 1 with location}
- {top finding 2 with location}
- {top finding 3 with location}

### Initial Assessment
> **Observation**: {overall health assessment}
> **Biggest Risk**: {highest severity pattern}
> **Quick Wins**: {low-effort high-impact items}

---

Phase 3: Assessment & Prioritization

Objective: Score, prioritize, and build an execution queue.

Workflow Steps:

1. Score Each Debt Item

For each item, assign via CLI analysis or heuristics:

• Impact (1-5): How much does this hurt? (5 = blocks development, causes bugs)
• Effort (1-5): How hard to fix? (1 = trivial, 5 = major rewrite)
• Priority Score = impact × (6 - effort) — favors high-impact low-effort items (e.g., impact=5 effort=1 → score=25; impact=2 effort=5 → score=2)

2. Dependency-Aware Ordering

Some items must be refactored before others:

• Extract shared types → then break circular dependency
• Fix base class → then fix subclasses

Build state.json.queue as an ordered array of item IDs.

3. Interactive Prioritization (skip in auto mode)

AskUserQuestion({
  questions: [{
    question: "技术债务优先级如何调整？",
    header: "Priorities",
    options: [
      { label: "确认优先级，开始重构", description: "按当前评分排序执行" },
      { label: "只处理 Critical/High", description: "跳过 Medium/Low 项，聚焦高优先级" },
      { label: "自定义选择", description: "手动选择要处理的债务项" },
      { label: "调整评分", description: "对某些项的 impact/effort 评分有不同意见" }
    ],
    multiSelect: false
  }]
})

4. Update state.json — write queue and update items with scores:

{
  "queue": ["D-003", "D-001", "D-007", "D-002"],
  "phase": "prioritized"
}

5. Capture baseline metrics — run tests + diagnostics before any changes:

// Run tests to get baseline pass count
// Run mcp__ide__getDiagnostics for baseline error count
// Save as state.json.baseline
{
  "baseline": {
    "test_pass_rate": 100,
    "test_count": 42,
    "diagnostic_errors": 3,
    "diagnostic_warnings": 15,
    "timestamp": ""
  }
}

6. Append to reflection-log.md (replace ## Phase 3: Prioritization placeholder):

## Phase 3: Prioritization - {timestamp}

### Priority Queue ({N} items)
| Rank | ID | Title | Severity | Impact | Effort | Score |
|------|----|-------|----------|--------|--------|-------|
| 1 | D-003 | ... | critical | 5 | 2 | 20 |
| 2 | D-001 | ... | high | 4 | 3 | 12 |
| ... | ... | ... | ... | ... | ... | ... |

### Prioritization Decisions
> **Decision**: {ordering rationale}
> - **Dependency constraint**: {D-X must precede D-Y because...}
> - **User adjustment**: {what was changed and why}

### Baseline Metrics
- Tests: {pass_rate}% ({count} tests)
- Diagnostics: {errors} errors, {warnings} warnings

---

Phase 4: Iterative Refactoring Cycle

Objective: Execute refactoring items one-by-one with per-item validation, reflection, and commit.

For each item in queue:

1. Plan     → Design specific refactoring approach
2. Refactor → @code-developer applies changes
3. Validate → Tests + diagnostics + quality check
4. Decision → PASS (commit + next) | PARTIAL (fix + retry) | FAIL (rollback + skip)
5. Reflect  → Record outcome in reflection-log.md
6. Commit   → Safe checkpoint

Max retries per item: 3 (then skip with note)

Step 4.1: Plan Refactoring

For each item, generate a focused refactoring plan:

Bash({
  command: `ccw cli -p "
PURPOSE: Design refactoring approach for debt item ${item.id}: ${item.title}
Success: Specific, minimal changes that resolve the debt without regression

DEBT ITEM:
${JSON.stringify(item, null, 2)}

CODEBASE CONTEXT:
${JSON.stringify(state.exploration, null, 2)}

TASK:
• Analyze the specific code at ${item.location}
• Design minimal refactoring approach (smallest change that fixes the debt)
• List exact files and functions to modify
• Identify regression risks and how to mitigate
• Define validation criteria (how to know it worked)

MODE: analysis
CONTEXT: @**/*
EXPECTED: Refactoring plan with: approach, modification_points [{file, function, change_description}], regression_risks, validation_criteria
CONSTRAINTS: Minimal changes | No behavior change | Preserve backward compatibility
" --tool gemini --mode analysis --rule development-refactor-codebase`,
  run_in_background: true
})

Save CLI output to .trace/item-${N}-cli.txt. Update state.json.debt_items[item].refactor_plan with parsed plan. Set state.json.current_item to item ID.

Step 4.2: Execute Refactoring

Task({
  subagent_type: "code-developer",
  run_in_background: false,
  description: `Refactor ${item.id}: ${item.title}`,
  prompt: `
## Task Objective
Apply refactoring for debt item ${item.id}: ${item.title}

## MANDATORY FIRST STEPS
1. Read state.json: ${sessionFolder}/state.json — use current_item and its refactor_plan
2. Read the source files at the modification points
3. Understand the existing behavior before changing anything

## Refactoring Plan
${JSON.stringify(item.refactor_plan, null, 2)}

## Critical Rules
- **No behavior change**: Refactoring must preserve existing functionality
- **Minimal diff**: Only change what's necessary to resolve the debt
- **Follow existing patterns**: Match naming, formatting, import style
- **No new dependencies**: Don't introduce new libraries
- **Backward compatible**: Preserve all public APIs and exports

## After Changes
- Verify syntax: Run tsc --noEmit or equivalent
- Check imports: Ensure no broken references
`
})

Step 4.3: Validate

// 1. Run tests
Task({
  subagent_type: "test-fix-agent",
  run_in_background: false,
  description: `Validate refactoring: ${item.id}`,
  prompt: `
## Task Objective
Validate that refactoring ${item.id} causes no regression.

## Validation Steps
1. Run full test suite — compare against baseline: ${state.baseline.test_pass_rate}% (${state.baseline.test_count} tests)
2. Check for new test failures (any failure not in baseline = regression)
3. Run syntax check (tsc --noEmit or equivalent)

## Output
Update state.json field "debt_items[${item.id}].validation_result" with:
{
  "tests_passed": true|false,
  "test_pass_rate": 0,
  "new_failures": [],
  "diagnostics_delta": { "errors": 0, "warnings": 0 },
  "regression_detected": false,
  "validation_criteria_met": true|false,
  "timestamp": ""
}
Save test output to: ${sessionFolder}/.trace/test-output.log
`
})

// 2. Check diagnostics
// mcp__ide__getDiagnostics — compare against baseline

Step 4.4: Decision & Retry

const result = item.validation_result;

if (result.tests_passed && !result.regression_detected && result.validation_criteria_met) {
  // PASS → commit, reflect, next item
  item.status = "completed";
} else if (retryCount < 3) {
  // PARTIAL → analyze failure, fix, retry
  // Use @test-fix-agent to fix regression
  retryCount++;
  // Loop back to 4.2 with fix context
} else {
  // FAIL → rollback, skip
  // git revert to last checkpoint
  item.status = "skipped";
  item.skip_reason = "Max retries reached, regression not resolved";
}

Step 4.5: Reflect

Append to reflection-log.md ## Refactoring Timeline:

### Item {item.id}: {item.title} — {COMPLETED|SKIPPED} ({timestamp})

**Changes**: {files modified}
**Validation**: Tests {pass_rate}% | Diagnostics delta: {errors_delta} errors, {warnings_delta} warnings
**Regression**: {none detected | description of regression}

**What Changed**: {concrete description of refactoring}
**What Broke** (if any): {regression details}
**What We Learned**: {insight about this debt pattern}
**Impact on Remaining Items**: {does this affect other queue items?}

Update ## Cumulative Learnings (replace, not append):

## Cumulative Learnings (Updated: Item {item.id})

### Safe Patterns
- {refactoring pattern that worked without regression}

### Risky Patterns
- {pattern that caused regression — avoid or handle carefully}

### Dependency Insights
- {discovered hidden dependencies during refactoring}

### Code Health Trend
- Items completed: {N}/{total}
- Regressions encountered: {N}
- Test health: {baseline → current}

Step 4.6: Commit

git add <modified_files>
git commit -m "refactor(${item.dimension}): ${item.title} [${item.id}]"

Move to next item in queue.

---

Phase 5: Completion

Objective: Compare final metrics against baseline, finalize reflection log.

Workflow Steps:

1. Final Metrics Capture — run tests + diagnostics again

2. Update state.json — write summary:

{
  "summary": {
    "result": "success|partial|incomplete",
    "items_completed": 0,
    "items_skipped": 0,
    "items_total": 0,
    "metrics_before": { "test_pass_rate": 0, "diagnostic_errors": 0, "diagnostic_warnings": 0 },
    "metrics_after": { "test_pass_rate": 0, "diagnostic_errors": 0, "diagnostic_warnings": 0 },
    "dimensions_addressed": { "code_quality": 0, "architecture": 0, "dependencies": 0, "test_gaps": 0, "maintainability": 0 },
    "regressions_encountered": 0,
    "key_learnings": [],
    "remaining_debt": [],
    "completed": "timestamp"
  },
  "phase": "completed"
}

3. Finalize reflection-log.md — replace ## Conclusions placeholder:

## Conclusions - {timestamp}

### Result: {SUCCESS|PARTIAL|INCOMPLETE}

### Metrics Comparison
| Metric | Before | After | Delta |
|--------|--------|-------|-------|
| Test Pass Rate | {X}% | {Y}% | {+/-Z}% |
| Diagnostic Errors | {X} | {Y} | {+/-Z} |
| Diagnostic Warnings | {X} | {Y} | {+/-Z} |

### Completed ({N}/{total})
| ID | Title | Dimension |
|----|-------|-----------|
| D-001 | ... | architecture |
| ... | ... | ... |

### Skipped ({N})
| ID | Title | Reason |
|----|-------|--------|
| D-005 | ... | Regression not resolvable in 3 retries |

### Remaining Debt
- {items not in queue or deferred}

### Key Insights
- {insight about codebase health}
- {pattern for future refactoring}

### Recommendations
- {what to address next}
- {process improvement}

4. Post-Completion Options (AskUserQuestion)

AskUserQuestion({
  questions: [{
    question: "重构完成，下一步？",
    header: "Next Steps",
    options: [
      { label: "创建Issue", description: "将剩余债务/跳过项创建为Issue跟踪" },
      { label: "继续处理", description: "处理跳过项或剩余低优先级债务" },
      { label: "生成报告", description: "导出完整的技术债务报告" },
      { label: "完成", description: "无需进一步操作" }
    ],
    multiSelect: false
  }]
})

---

Debt Dimensions Reference

Dimension	What to Scan	Severity Signals
Code Quality	Cyclomatic complexity >10, duplication >20 lines, dead code, long files >500 lines, deep nesting >4	Critical: dead code in critical path; High: >15 complexity
Architecture	Coupling >5 imports from one module, layering violations, god classes >300 lines, missing abstractions	Critical: circular dependency in core; High: layering violation
Dependencies	Circular imports, unused deps, outdated with CVEs, version conflicts	Critical: known CVE; High: circular in core modules
Test Gaps	Untested critical paths, fragile tests, missing edge cases, mock leakage	Critical: no tests for auth/payment; High: flaky CI tests
Maintainability	any/@ts-ignore abuse, magic numbers, misleading names, missing types	High: >10 suppressions in one file; Medium: inconsistent naming

---

state.json Full Schema

{
  "session_id": "RFT-xxx",
  "target": "description",
  "scope": "module|project",
  "started": "timestamp",
  "phase": "init|explored|prioritized|refactoring|completed",

  "exploration": {
    "structure": { "files": [], "modules": [], "total_loc": 0 },
    "metrics": { "largest_files": [], "most_complex": [], "deepest_nesting": [] },
    "dependency_issues": { "circular": [], "unused_imports": [], "outdated_deps": [] },
    "test_mapping": { "tested": [], "untested": [], "coverage_estimate": "" },
    "pattern_violations": { "suppressions": [], "todos": [], "inconsistencies": [] },
    "_metadata": { "files_analyzed": 0, "timestamp": "" }
  },

  "debt_items": [{
    "id": "D-001",
    "dimension": "architecture",
    "title": "",
    "location": "",
    "severity": "critical|high|medium|low",
    "description": "",
    "suggested_fix": "",
    "impact": 0,
    "effort": 0,
    "priority_score": 0,
    "status": "discovered|queued|in_progress|completed|skipped",
    "refactor_plan": { "approach": "", "modification_points": [], "regression_risks": [], "validation_criteria": [] },
    "validation_result": { "tests_passed": false, "regression_detected": false, "diagnostics_delta": {} },
    "skip_reason": null
  }],

  "queue": [],
  "current_item": null,
  "completed_items": [],
  "skipped_items": [],

  "baseline": {
    "test_pass_rate": 0,
    "test_count": 0,
    "diagnostic_errors": 0,
    "diagnostic_warnings": 0,
    "timestamp": ""
  },

  "summary": {
    "result": "success|partial|incomplete",
    "items_completed": 0,
    "items_skipped": 0,
    "items_total": 0,
    "metrics_before": {},
    "metrics_after": {},
    "dimensions_addressed": {},
    "regressions_encountered": 0,
    "key_learnings": [],
    "remaining_debt": [],
    "completed": ""
  }
}

---

Error Handling

Scenario	Action
cli-explore-agent fails	Fallback to Grep/Glob manual scan
CLI analysis timeout	Fallback: Gemini → Qwen → Codex
Test suite crashes	Log error, retry with minimal test subset
Regression in refactoring	Retry up to 3 times, then rollback + skip
All items skipped	Generate failure report, recommend manual review
Circular dependency in queue	Detect in Phase 3, break cycle with extraction item
Diagnostics unavailable	Skip diagnostics check, rely on tests only

CLI Fallback Chain: Gemini → Qwen → Codex

---

Commit Strategy

1. Before refactoring starts (Phase 3 baseline):

   git stash  # Save any uncommitted work
   

2. After each completed item:

   git add <modified_files>
   git commit -m "refactor(${dimension}): ${title} [${id}]"
   

3. On regression (rollback):

   git checkout -- <modified_files>  # Discard changes for this item
   

4. Final completion commit:

   git add ${sessionFolder}/reflection-log.md ${sessionFolder}/state.json
   git commit -m "refactor: complete tech debt cycle ${sessionId} (${completed}/${total} items)"
   

---

Best Practices

1. Start with module scope: Project-wide scans produce too many items; focus on one module first
2. Trust prioritization: Impact × effort scoring avoids analysis paralysis
3. One item at a time: Each refactoring is isolated, validated, and committed
4. Rollback is not failure: Skipping a risky item is better than introducing regression
5. Review reflection-log.md: Cumulative learnings help future refactoring sessions
6. Auto mode for cleanup: Use -y for straightforward tech debt (naming, dead code)
7. Interactive for architecture: Complex architectural refactoring benefits from user input at prioritization

---

Usage Recommendations

Use this command when:

• Systematic tech debt cleanup needed for a module
• Pre-refactoring analysis and prioritization required
• Need regression-safe iterative refactoring with rollback
• Want documented reasoning for each refactoring decision

Use /workflow:lite-fix when:

• Single specific bug or issue to fix
• No systematic debt analysis needed

Use /workflow:plan + /workflow:execute when:

• New feature implementation (not refactoring)
• Already know exactly what to change

Use /workflow:integration-test-cycle when:

• Need integration tests before/after refactoring
• Want to verify cross-module behavior post-refactoring

---

Post-Completion Expansion

完成后询问用户是否扩展为issue(test/enhance/refactor/doc)，选中项调用 /issue:new "{summary} - {dimension}"

---

Now execute refactor-cycle for: $ARGUMENTS