claude-code-workflow 7.2.30 → 7.3.0

package/.claude/skills/ccw-chain/phases/refactor-cycle.md

@@ -1,852 +0,0 @@
----
-name: refactor-cycle
-description: Tech debt discovery and self-iterating refactoring with multi-dimensional analysis, prioritized execution, regression validation, and reflection-driven adjustment
-argument-hint: "[-y|--yes] [-c|--continue] [--scope=module|project] \"module or refactoring goal\""
-allowed-tools: TodoWrite(*), Agent(*), 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
-
-```bash
-# 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**:
-
-```markdown
-# 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**:
-
-```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**
-
-```javascript
-Agent({
-  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**
-
-```javascript
-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`:
-
-```json
-[
-  {
-    "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):
-
-```markdown
-## 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)
-
-```javascript
-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:
-
-```json
-{
-  "queue": ["D-003", "D-001", "D-007", "D-002"],
-  "phase": "prioritized"
-}
-```
-
-5. **Capture baseline metrics** — run tests + diagnostics before any changes:
-
-```javascript
-// 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):
-
-```markdown
-## 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:
-
-```javascript
-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
-
-```javascript
-Agent({
-  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
-
-```javascript
-// 1. Run tests
-Agent({
-  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
-
-```javascript
-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`:
-
-```markdown
-### 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):
-
-```markdown
-## 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
-
-```bash
-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`:
-
-```json
-{
-  "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:
-
-```markdown
-## 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)
-
-```javascript
-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
-
-```json
-{
-  "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):
-   ```bash
-   git stash  # Save any uncommitted work
-   ```
-
-2. **After each completed item**:
-   ```bash
-   git add <modified_files>
-   git commit -m "refactor(${dimension}): ${title} [${id}]"
-   ```
-
-3. **On regression (rollback)**:
-   ```bash
-   git checkout -- <modified_files>  # Discard changes for this item
-   ```
-
-4. **Final completion commit**:
-   ```bash
-   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-plan` skill when:**
-- Single specific bug or issue to fix
-- No systematic debt analysis needed
-
-**Use `workflow-plan` skill + `workflow-execute` skill 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
-
-**Auto-sync**: 执行 `/workflow:session:sync -y "{summary}"` 更新 specs/*.md + project-tech。
-
-完成后询问用户是否扩展为issue(test/enhance/refactor/doc)，选中项调用 `/issue:new "{summary} - {dimension}"`
-
----
-
-**Now execute refactor-cycle for**: $ARGUMENTS