mirror of
https://github.com/catlog22/Claude-Code-Workflow.git
synced 2026-02-15 02:42:45 +08:00
feat: add integration-test-cycle and refactor-cycle workflow commands
Two new self-iterating workflow commands with minimal artifacts pattern (reflection-log.md + state.json + .trace/): - integration-test-cycle: explore → design → develop → test → reflect → adjust - refactor-cycle: discover debt → assess → prioritize → refactor → validate → reflect
This commit is contained in:
catlog22
932
.claude/commands/workflow/integration-test-cycle.md
Normal file
932
.claude/commands/workflow/integration-test-cycle.md
Normal file
@@ -0,0 +1,932 @@
|
||||
---
|
||||
name: integration-test-cycle
|
||||
description: Self-iterating integration test workflow with codebase exploration, test development, autonomous test-fix cycles, and reflection-driven strategy adjustment
|
||||
argument-hint: "[-y|--yes] [-c|--continue] [--max-iterations=N] \"module or feature description\""
|
||||
allowed-tools: TodoWrite(*), Task(*), AskUserQuestion(*), Read(*), Grep(*), Glob(*), Bash(*), Edit(*), Write(*), Skill(*)
|
||||
---
|
||||
|
||||
## Auto Mode
|
||||
|
||||
When `--yes` or `-y`: Auto-confirm exploration decisions, use recommended test strategies, skip interactive checkpoints.
|
||||
|
||||
# Workflow Integration-Test-Cycle Command
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Basic - explore and test a module
|
||||
/workflow:integration-test-cycle "用户认证模块的集成测试"
|
||||
|
||||
# Auto mode - fully autonomous
|
||||
/workflow:integration-test-cycle -y "支付流程端到端集成测试"
|
||||
|
||||
# Continue interrupted session
|
||||
/workflow:integration-test-cycle --continue "认证模块"
|
||||
|
||||
# Custom iteration limit
|
||||
/workflow:integration-test-cycle --max-iterations=15 "API网关集成测试"
|
||||
```
|
||||
|
||||
**Context Source**: cli-explore-agent + Gemini/Codex analysis
|
||||
**Output Directory**: `.workflow/.integration-test/{session-id}/`
|
||||
**Core Innovation**: Reflection-driven self-iterating test cycle with documented learning evolution
|
||||
|
||||
## What & Why
|
||||
|
||||
### Core Concept
|
||||
|
||||
Unified integration test workflow: **Explore → Design → Develop → Test → Reflect → Adjust → Re-test** — a closed-loop that autonomously improves test quality through text-based reflection.
|
||||
|
||||
**vs Existing Commands**:
|
||||
- **test-fix-gen**: Only generates test tasks, requires manual `/test-cycle-execute`
|
||||
- **test-cycle-execute**: Only executes pre-existing tasks, no exploration or test design
|
||||
- **This command**: Full lifecycle — from zero knowledge to passing integration tests, with self-reflection
|
||||
|
||||
### Value Proposition
|
||||
1. **Zero-to-Tests**: No prior session needed — starts from exploration
|
||||
2. **Self-Improving**: Reflection log drives strategy adjustment between iterations
|
||||
3. **Integration Focus**: Specifically targets cross-module boundaries and API contracts
|
||||
4. **Documented Learning**: Every decision, failure, and adjustment recorded in reflection-log.md
|
||||
|
||||
## Output Artifacts
|
||||
|
||||
**2 核心文件 + 1 追踪目录**，全流程产物最小化：
|
||||
|
||||
| Artifact | Type | Description |
|
||||
|----------|------|-------------|
|
||||
| `reflection-log.md` | 人类可读 | ⭐ 唯一文本文档：探索发现、设计决策、迭代反思、累积认知、最终结论 |
|
||||
| `state.json` | 机器可读 | 唯一状态文件：探索上下文、测试设计、测试清单、迭代状态、测试结果、修复历史、最终摘要 |
|
||||
| `.trace/` | 原始日志 | CLI 输出和测试日志，仅调试用：`cli-{N}.txt`、`test-output.log` |
|
||||
|
||||
```
|
||||
.workflow/.integration-test/ITG-{slug}-{date}/
|
||||
├── reflection-log.md # ⭐ 唯一人类可读文档 (exploration + design + iterations + conclusions)
|
||||
├── state.json # 唯一机器状态 (exploration + design + inventory + iterations + results + summary)
|
||||
└── .trace/ # 原始日志 (仅调试参考)
|
||||
├── cli-1.txt
|
||||
├── cli-2.txt
|
||||
└── test-output.log
|
||||
```
|
||||
|
||||
## Overview
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ SELF-ITERATING INTEGRATION TEST WORKFLOW │
|
||||
├─────────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ Phase 1: Session Initialization │
|
||||
│ ├─ Parse input (module description) │
|
||||
│ ├─ Create session directory │
|
||||
│ └─ Initialize reflection-log.md + state.json │
|
||||
│ │
|
||||
│ Phase 2: Codebase Exploration │
|
||||
│ ├─ cli-explore-agent: Module structure & dependencies │
|
||||
│ ├─ Identify integration points & boundaries │
|
||||
│ ├─ Map cross-module data flows │
|
||||
│ ├─ Write state.json.exploration │
|
||||
│ └─ Append exploration findings to reflection-log.md │
|
||||
│ │
|
||||
│ Phase 3: Integration Test Design │
|
||||
│ ├─ CLI analysis: Design test strategy │
|
||||
│ ├─ Define integration scenarios │
|
||||
│ ├─ [Interactive] User confirms/adjusts strategy │
|
||||
│ ├─ Write state.json.test_design │
|
||||
│ └─ Append design decisions to reflection-log.md │
|
||||
│ │
|
||||
│ Phase 4: Test Development │
|
||||
│ ├─ @code-developer: Generate integration tests │
|
||||
│ ├─ Code validation (imports, types, mocks) │
|
||||
│ ├─ Write state.json.test_inventory │
|
||||
│ └─ Append development notes to reflection-log.md │
|
||||
│ │
|
||||
│ Phase 5: Self-Iterating Test Cycle ◄─── CORE LOOP ──┐ │
|
||||
│ ├─ Execute tests │ │
|
||||
│ ├─ Calculate pass rate │ │
|
||||
│ ├─ Decision: │ │
|
||||
│ │ ├─ >= 95% → Phase 6 (Complete) │ │
|
||||
│ │ └─ < 95% → Reflect & Adjust ──────────────────→ │ │
|
||||
│ │ ├─ Inline reflection to reflection-log.md │ │
|
||||
│ │ ├─ Update state.json.iterations │ │
|
||||
│ │ ├─ Select strategy based on cumulative learnings │
|
||||
│ │ ├─ @cli-planning-agent: Analyze failures │ │
|
||||
│ │ ├─ @test-fix-agent: Apply fixes │ │
|
||||
│ │ └─ Loop │ │
|
||||
│ └─ Max iterations check (default: 10) │
|
||||
│ │
|
||||
│ Phase 6: Completion │
|
||||
│ ├─ Write state.json.summary │
|
||||
│ ├─ 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/feature description from `$ARGUMENTS`
|
||||
2. Generate session ID: `ITG-{slug}-{date}`
|
||||
- slug: lowercase, alphanumeric + Chinese, max 40 chars
|
||||
- date: YYYY-MM-DD (UTC+8)
|
||||
3. Define session folder: `.workflow/.integration-test/{session-id}`
|
||||
4. Parse command options:
|
||||
- `-c` or `--continue` for session continuation
|
||||
- `-y` or `--yes` for auto-approval mode
|
||||
- `--max-iterations=N` (default: 10)
|
||||
5. Auto-detect mode: If session folder + reflection-log.md exist → continue mode
|
||||
6. Create directory structure: `{sessionFolder}/`, `{sessionFolder}/.trace/`
|
||||
|
||||
**Initialize reflection-log.md**:
|
||||
|
||||
```markdown
|
||||
# Integration Test Reflection Log
|
||||
|
||||
## Session: {sessionId}
|
||||
- **Topic**: {module_or_feature_description}
|
||||
- **Started**: {timestamp}
|
||||
- **Mode**: {new|continue}
|
||||
- **Max Iterations**: {maxIterations}
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Exploration
|
||||
> Pending...
|
||||
|
||||
## Phase 3: Test Design
|
||||
> Pending...
|
||||
|
||||
## Phase 4: Test Development
|
||||
> Pending...
|
||||
|
||||
## Iteration Timeline
|
||||
> Iterations will be appended here...
|
||||
|
||||
## Cumulative Learnings
|
||||
> Updated after each iteration...
|
||||
|
||||
## Conclusions
|
||||
> Final synthesis after completion...
|
||||
```
|
||||
|
||||
**Initialize state.json**:
|
||||
|
||||
```json
|
||||
{
|
||||
"session_id": "{sessionId}",
|
||||
"module": "{module_description}",
|
||||
"started": "{timestamp}",
|
||||
"max_iterations": 10,
|
||||
"phase": "init",
|
||||
"exploration": null,
|
||||
"test_design": null,
|
||||
"test_inventory": null,
|
||||
"iterations": {
|
||||
"current": 0,
|
||||
"strategy": null,
|
||||
"next_action": "explore",
|
||||
"history": [],
|
||||
"stuck_tests": [],
|
||||
"latest_results": null
|
||||
},
|
||||
"fix_history": [],
|
||||
"summary": null
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Codebase Exploration
|
||||
|
||||
**Objective**: Deep-dive into the target module, identify integration points, dependencies, and data flows.
|
||||
|
||||
**Workflow Steps**:
|
||||
|
||||
1. **Codebase Exploration via cli-explore-agent**
|
||||
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: "cli-explore-agent",
|
||||
run_in_background: false,
|
||||
description: `Explore integration points: ${topicSlug}`,
|
||||
prompt: `
|
||||
## Analysis Context
|
||||
Topic: ${module_description}
|
||||
Session: ${sessionFolder}
|
||||
|
||||
## MANDATORY FIRST STEPS
|
||||
1. Run: ccw tool exec get_modules_by_depth '{}'
|
||||
2. Execute relevant searches: module boundaries, exported APIs, shared types
|
||||
3. Read: .workflow/project-tech.json (if exists)
|
||||
|
||||
## Exploration Focus
|
||||
- **Module Boundaries**: Entry points, public APIs, exported interfaces
|
||||
- **Dependencies**: What this module depends on, what depends on it
|
||||
- **Integration Points**: Cross-module calls, shared state, event flows
|
||||
- **Data Contracts**: Types, schemas, validation at boundaries
|
||||
- **Existing Tests**: Current test patterns, test utilities, mocking conventions
|
||||
- **Configuration**: Environment dependencies, feature flags, external services
|
||||
|
||||
## Output
|
||||
Update state.json field "exploration" with:
|
||||
{
|
||||
"module_structure": { "entry_points": [], "public_apis": [], "internal_modules": [] },
|
||||
"dependencies": { "upstream": [], "downstream": [], "external_services": [] },
|
||||
"integration_points": [{ "from": "", "to": "", "type": "api|event|shared_state", "contract": "" }],
|
||||
"data_flows": [{ "name": "", "path": [], "transforms": [] }],
|
||||
"existing_tests": { "test_files": [], "patterns": [], "utilities": [], "mocking_conventions": "" },
|
||||
"test_framework": { "runner": "", "assertion_lib": "", "mock_lib": "" },
|
||||
"risk_areas": [{ "area": "", "reason": "", "priority": "high|medium|low" }],
|
||||
"_metadata": { "files_analyzed": 0, "timestamp": "" }
|
||||
}
|
||||
|
||||
Also set state.json "phase" to "explored".
|
||||
`
|
||||
})
|
||||
```
|
||||
|
||||
2. **Append to reflection-log.md** (replace `## Phase 2: Exploration` placeholder):
|
||||
|
||||
```markdown
|
||||
## Phase 2: Exploration - {timestamp}
|
||||
|
||||
### What We Found
|
||||
- **Module Boundaries**: {summary of entry points and APIs}
|
||||
- **Integration Points**: {N} cross-module connections identified
|
||||
- **Data Flows**: {key data flow paths}
|
||||
- **Existing Test Patterns**: {test framework, conventions}
|
||||
|
||||
### Initial Assumptions
|
||||
- {assumption_1}: {basis}
|
||||
- {assumption_2}: {basis}
|
||||
|
||||
### Risk Areas
|
||||
- {risk_1}: {why risky for integration testing}
|
||||
|
||||
### Decision Log
|
||||
> **Decision**: Focus integration testing on {specific boundaries}
|
||||
> - **Context**: Exploration revealed {N} integration points
|
||||
> - **Chosen**: {approach} — **Reason**: {rationale}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Integration Test Design
|
||||
|
||||
**Objective**: Design integration test strategy based on exploration findings.
|
||||
|
||||
**Workflow Steps**:
|
||||
|
||||
1. **CLI Analysis for Test Strategy Design**
|
||||
|
||||
```javascript
|
||||
Bash({
|
||||
command: `ccw cli -p "
|
||||
PURPOSE: Design integration test strategy for '${module_description}' based on exploration findings
|
||||
Success: Comprehensive test design covering all critical integration points
|
||||
|
||||
EXPLORATION CONTEXT:
|
||||
${JSON.stringify(state.exploration, null, 2)}
|
||||
|
||||
TASK:
|
||||
• Analyze integration points and prioritize by risk
|
||||
• Design test scenarios for each critical integration boundary
|
||||
• Define mocking strategy: what to mock vs what to test end-to-end
|
||||
• Specify test data setup and teardown patterns
|
||||
• Define success criteria per scenario
|
||||
|
||||
MODE: analysis
|
||||
CONTEXT: @**/* | Module: ${module_description}
|
||||
EXPECTED: Structured test design with: integration scenarios (grouped by boundary), mocking strategy, test data patterns, execution order, success criteria per scenario
|
||||
CONSTRAINTS: Focus on integration boundaries | Follow existing test patterns | Avoid duplicating unit tests
|
||||
" --tool gemini --mode analysis --rule analysis-analyze-code-patterns`,
|
||||
run_in_background: true
|
||||
})
|
||||
```
|
||||
|
||||
2. **Interactive Strategy Confirmation** (skip in auto mode)
|
||||
|
||||
```javascript
|
||||
AskUserQuestion({
|
||||
questions: [{
|
||||
question: "集成测试策略如何调整？",
|
||||
header: "Test Strategy",
|
||||
options: [
|
||||
{ label: "确认策略，开始开发", description: "当前测试设计方案合理，直接开始生成测试" },
|
||||
{ label: "调整测试范围", description: "需要扩大或缩小集成测试覆盖范围" },
|
||||
{ label: "修改Mock策略", description: "对哪些模块需要Mock有不同意见" },
|
||||
{ label: "补充测试场景", description: "有额外的集成测试场景需要覆盖" }
|
||||
],
|
||||
multiSelect: false
|
||||
}]
|
||||
})
|
||||
```
|
||||
|
||||
3. **Update state.json** — write `test_design` field:
|
||||
|
||||
```json
|
||||
{
|
||||
"test_design": {
|
||||
"integration_scenarios": [
|
||||
{
|
||||
"id": "IS-001",
|
||||
"name": "scenario name",
|
||||
"boundary": "moduleA → moduleB",
|
||||
"type": "api_contract|event_flow|shared_state|data_pipeline",
|
||||
"priority": "critical|high|medium",
|
||||
"test_cases": [
|
||||
{ "name": "happy path", "input": "", "expected": "", "assertion_type": "" },
|
||||
{ "name": "error propagation", "input": "", "expected": "" },
|
||||
{ "name": "boundary condition", "input": "", "expected": "" }
|
||||
],
|
||||
"mocking": { "mock_targets": [], "real_targets": [], "reason": "" },
|
||||
"setup": "description",
|
||||
"teardown": "description"
|
||||
}
|
||||
],
|
||||
"mocking_strategy": {
|
||||
"approach": "minimal|moderate|heavy",
|
||||
"mock_boundaries": [],
|
||||
"real_boundaries": [],
|
||||
"rationale": ""
|
||||
},
|
||||
"execution_order": ["IS-001", "IS-002"],
|
||||
"success_criteria": { "pass_rate": 95, "coverage_target": 80 }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Also set `state.json.phase` to `"designed"`.
|
||||
|
||||
4. **Append to reflection-log.md** (replace `## Phase 3: Test Design` placeholder):
|
||||
|
||||
```markdown
|
||||
## Phase 3: Test Design - {timestamp}
|
||||
|
||||
### Strategy Summary
|
||||
- **Total Scenarios**: {N} integration scenarios
|
||||
- **Priority Distribution**: {N} critical, {N} high, {N} medium
|
||||
- **Mocking Approach**: {minimal|moderate|heavy}
|
||||
|
||||
### Design Decisions
|
||||
> **Decision**: {mocking strategy choice}
|
||||
> - **Chosen**: {approach} — **Reason**: {rationale}
|
||||
|
||||
### User Feedback
|
||||
- {user_adjustment_if_any}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: Test Development
|
||||
|
||||
**Objective**: Generate integration test code based on the test design.
|
||||
|
||||
**Workflow Steps**:
|
||||
|
||||
1. **Generate Integration Tests via @code-developer**
|
||||
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: "code-developer",
|
||||
run_in_background: false,
|
||||
description: `Generate integration tests: ${topicSlug}`,
|
||||
prompt: `
|
||||
## Task Objective
|
||||
Generate integration tests based on test design specification.
|
||||
|
||||
## MANDATORY FIRST STEPS
|
||||
1. Read state.json: ${sessionFolder}/state.json — use "exploration" and "test_design" fields
|
||||
2. Identify existing test patterns in the codebase
|
||||
3. Read relevant source files for each integration boundary
|
||||
|
||||
## Test Development Requirements
|
||||
- Follow existing test framework and conventions (from state.json.exploration.test_framework)
|
||||
- One test file per integration boundary (or logical grouping)
|
||||
- Include: test data setup, scenario execution, assertions, cleanup
|
||||
- Use mocking strategy from state.json.test_design.mocking_strategy
|
||||
- Cover all test cases defined in integration_scenarios
|
||||
- Add descriptive test names: "should {behavior} when {condition}"
|
||||
|
||||
## Code Quality
|
||||
- No hallucinated imports - verify every import exists
|
||||
- No placeholder/TODO code - all tests must be executable
|
||||
- Proper async/await handling
|
||||
- Proper error assertion (expect specific error types/messages)
|
||||
|
||||
## Output
|
||||
1. Write test files to appropriate directories following project conventions
|
||||
2. Update state.json field "test_inventory" with:
|
||||
{
|
||||
"test_files": [{ "path": "", "scenario_ids": [], "test_count": 0, "boundary": "" }],
|
||||
"total_tests": 0,
|
||||
"total_files": 0,
|
||||
"timestamp": ""
|
||||
}
|
||||
Also set state.json "phase" to "developed".
|
||||
`
|
||||
})
|
||||
```
|
||||
|
||||
2. **Code Validation Gate via @test-fix-agent**
|
||||
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: "test-fix-agent",
|
||||
run_in_background: false,
|
||||
description: `Validate generated tests: ${topicSlug}`,
|
||||
prompt: `
|
||||
## Task Objective
|
||||
Validate generated integration test code for common AI-generated issues.
|
||||
|
||||
## MANDATORY FIRST STEPS
|
||||
1. Read state.json: ${sessionFolder}/state.json — use "test_inventory" field for file list
|
||||
2. Read each test file listed in test_inventory.test_files
|
||||
|
||||
## Validation Checklist
|
||||
- [ ] All imports resolve to existing modules
|
||||
- [ ] No placeholder or TODO code blocks
|
||||
- [ ] Mock setup matches actual module interfaces
|
||||
- [ ] Async operations properly awaited
|
||||
- [ ] Test assertions are specific (not just "toBeTruthy")
|
||||
- [ ] Cleanup/teardown properly implemented
|
||||
- [ ] TypeScript types correct (run tsc --noEmit if applicable)
|
||||
|
||||
## On Validation Failure
|
||||
- Fix issues directly in test files
|
||||
- Log fixes to: ${sessionFolder}/.trace/validation-fixes.log
|
||||
`
|
||||
})
|
||||
```
|
||||
|
||||
3. **Append to reflection-log.md** (replace `## Phase 4: Test Development` placeholder):
|
||||
|
||||
```markdown
|
||||
## Phase 4: Test Development - {timestamp}
|
||||
|
||||
### Generated Tests
|
||||
- **Files**: {N} test files
|
||||
- **Total Tests**: {N} test cases
|
||||
- **Scenarios Covered**: {list}
|
||||
|
||||
### Validation Results
|
||||
- Issues Found: {N}, Fixed: {N}
|
||||
|
||||
### Development Notes
|
||||
- {notable patterns used}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 5: Self-Iterating Test Cycle
|
||||
|
||||
**Objective**: Execute tests, analyze failures, reflect, adjust strategy, fix, and re-test until pass rate >= 95% or max iterations.
|
||||
|
||||
**Quality Gate**: Pass rate >= 95% (criticality-aware) or 100%
|
||||
**Max Iterations**: From session config (default: 10)
|
||||
|
||||
#### Iteration Loop
|
||||
|
||||
```
|
||||
for iteration = 1 to maxIterations:
|
||||
1. Execute Tests → update state.json.iterations.latest_results
|
||||
2. Evaluate: 100% → SUCCESS | >= 95% low-crit → PARTIAL | < 95% → step 3
|
||||
3. Reflect → append inline to reflection-log.md
|
||||
4. Select Strategy (reflection-informed)
|
||||
5. Analyze & Fix → save CLI output to .trace/cli-{N}.txt
|
||||
6. Loop back to step 1
|
||||
```
|
||||
|
||||
#### Strategy Engine (Reflection-Enhanced)
|
||||
|
||||
| Strategy | Trigger | Behavior |
|
||||
|----------|---------|----------|
|
||||
| **Conservative** | Iteration 1-2 (default) | Single targeted fix, full validation |
|
||||
| **Aggressive** | Pass rate >80% + similar failures | Batch fix related issues |
|
||||
| **Surgical** | Regression detected (pass rate drops >10%) | Minimal changes, rollback focus |
|
||||
| **Reflective** | Same tests stuck 3+ iterations | Re-examine assumptions, redesign test |
|
||||
|
||||
```javascript
|
||||
function selectStrategy(iteration, passRate, stuckTests) {
|
||||
if (regressionDetected) return "surgical";
|
||||
if (stuckTests.length > 0 && stuckTestIterations >= 3) return "reflective";
|
||||
if (iteration <= 2) return "conservative";
|
||||
if (passRate > 80 && failurePattern.similarity > 0.7) return "aggressive";
|
||||
return "conservative";
|
||||
}
|
||||
```
|
||||
|
||||
#### Inline Reflection Format (appended to reflection-log.md `## Iteration Timeline`)
|
||||
|
||||
Each iteration appends one section directly into reflection-log.md (no separate files):
|
||||
|
||||
```markdown
|
||||
### Iteration {N} - {timestamp}
|
||||
|
||||
**Results**: {pass_rate}% ({passed}/{total}) | Strategy: {strategy}
|
||||
**Failed**: {test_list}
|
||||
|
||||
**Why It Failed**: {root cause analysis}
|
||||
**Assumed vs Reality**: {gap description}
|
||||
**Learned**: {key takeaway}
|
||||
**Next Action**: {strategy adjustment or specific fix plan}
|
||||
```
|
||||
|
||||
#### state.json Iteration Update
|
||||
|
||||
After each iteration, update `state.json.iterations`:
|
||||
|
||||
```json
|
||||
{
|
||||
"iterations": {
|
||||
"current": 3,
|
||||
"strategy": "aggressive",
|
||||
"next_action": "execute_fix",
|
||||
"history": [
|
||||
{
|
||||
"iteration": 1,
|
||||
"pass_rate": 70,
|
||||
"strategy": "conservative",
|
||||
"failed_tests": ["test_auth_integration", "test_payment_flow"],
|
||||
"reflection_summary": "Auth token not propagated to payment service",
|
||||
"strategy_adjustment": "none"
|
||||
},
|
||||
{
|
||||
"iteration": 2,
|
||||
"pass_rate": 82,
|
||||
"strategy": "conservative",
|
||||
"failed_tests": ["test_payment_flow"],
|
||||
"reflection_summary": "Payment timeout too short for integration",
|
||||
"strategy_adjustment": "aggressive - similar timeout failures"
|
||||
}
|
||||
],
|
||||
"stuck_tests": [],
|
||||
"latest_results": {
|
||||
"pass_rate": 82,
|
||||
"passed": 9,
|
||||
"failed": 2,
|
||||
"total": 11,
|
||||
"failures": [
|
||||
{ "test": "", "file": "", "error": "", "criticality": "high|medium|low" }
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Cumulative Learnings Update
|
||||
|
||||
After each iteration, update the `## Cumulative Learnings` section in reflection-log.md (replace, not append):
|
||||
|
||||
```markdown
|
||||
## Cumulative Learnings (Updated: Iteration {N})
|
||||
|
||||
### Confirmed Understanding
|
||||
- {verified facts}
|
||||
|
||||
### Corrected Assumptions
|
||||
- ~~{old}~~ → {new} (Iteration {N})
|
||||
|
||||
### Effective Strategies
|
||||
- {what worked}: {context}
|
||||
|
||||
### Ineffective Strategies
|
||||
- {what didn't work}: {why}
|
||||
|
||||
### Recurring Patterns
|
||||
- {pattern}: root cause {cause}
|
||||
```
|
||||
|
||||
#### Agent Invocations
|
||||
|
||||
**@test-fix-agent** (test execution):
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: "test-fix-agent",
|
||||
run_in_background: false,
|
||||
description: `Execute integration tests: iteration ${N}`,
|
||||
prompt: `
|
||||
## Task Objective
|
||||
Execute integration test suite and report results with criticality assessment.
|
||||
|
||||
## MANDATORY FIRST STEPS
|
||||
1. Read state.json: ${sessionFolder}/state.json — use "test_inventory" for test files
|
||||
${isFixIteration ? `2. Read fix strategy from state.json.fix_history (latest entry)` : ''}
|
||||
|
||||
## Test Execution
|
||||
${progressiveMode
|
||||
? `- Run affected tests only: ${affectedTests.join(' ')}`
|
||||
: '- Run full integration test suite'}
|
||||
|
||||
## Criticality Assessment
|
||||
For each failure, assign:
|
||||
- **high**: Core integration broken, data corruption risk
|
||||
- **medium**: Feature degradation, partial failure
|
||||
- **low**: Edge case, flaky, environment-specific
|
||||
|
||||
## Output
|
||||
- Update state.json field "iterations.latest_results" with test results
|
||||
- Overwrite ${sessionFolder}/.trace/test-output.log with full output
|
||||
`
|
||||
})
|
||||
```
|
||||
|
||||
**@cli-planning-agent** (failure analysis with reflection):
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: "cli-planning-agent",
|
||||
run_in_background: false,
|
||||
description: `Analyze failures: iteration ${N} - ${strategy}`,
|
||||
prompt: `
|
||||
## Task Objective
|
||||
Analyze test failures using reflection context and generate fix strategy.
|
||||
|
||||
## MANDATORY FIRST STEPS
|
||||
1. Read state.json: ${sessionFolder}/state.json — use "iterations" for history
|
||||
2. Read test output: ${sessionFolder}/.trace/test-output.log
|
||||
3. Read reflection-log.md: ${sessionFolder}/reflection-log.md — "Cumulative Learnings" section
|
||||
|
||||
## Reflection Context (CRITICAL)
|
||||
- **Iteration History**: ${state.iterations.history}
|
||||
- **Stuck Tests**: ${state.iterations.stuck_tests}
|
||||
- **What hasn't worked**: Read from "Ineffective Strategies" in reflection-log.md
|
||||
|
||||
## Strategy: ${selectedStrategy}
|
||||
- Conservative: Single targeted fix, verify no regression
|
||||
- Aggressive: Batch fix similar failures
|
||||
- Surgical: Minimal changes, rollback-safe
|
||||
- Reflective: Challenge assumptions, propose alternative test approach
|
||||
|
||||
## Expected Deliverables
|
||||
1. Append fix entry to state.json "fix_history" array:
|
||||
{ "iteration": ${N}, "strategy": "", "modification_points": [], "affected_tests": [], "confidence": 0.0 }
|
||||
2. Save CLI output to: ${sessionFolder}/.trace/cli-${N}.txt
|
||||
|
||||
## Success Criteria
|
||||
- Root cause identified (not symptoms)
|
||||
- Fix strategy with specific modification points
|
||||
- Affected tests listed for progressive testing
|
||||
`
|
||||
})
|
||||
```
|
||||
|
||||
**@test-fix-agent** (apply fixes):
|
||||
```javascript
|
||||
Task({
|
||||
subagent_type: "test-fix-agent",
|
||||
run_in_background: false,
|
||||
description: `Apply fixes: iteration ${N} - ${strategy}`,
|
||||
prompt: `
|
||||
## Task Objective
|
||||
Apply fixes from analysis and validate with targeted tests.
|
||||
|
||||
## MANDATORY FIRST STEPS
|
||||
1. Read state.json: ${sessionFolder}/state.json — use latest "fix_history" entry
|
||||
2. Run project syntax checker before any code modification
|
||||
|
||||
## Fix Application
|
||||
- Apply modifications from fix_history[latest].modification_points
|
||||
- Test execution: ${progressiveMode ? 'affected tests only' : 'full suite'}
|
||||
${progressiveMode ? `- Affected tests: ${affectedTests.join(' ')}` : ''}
|
||||
|
||||
## Output
|
||||
- Update state.json "iterations.latest_results" with new test results
|
||||
- Overwrite ${sessionFolder}/.trace/test-output.log
|
||||
`
|
||||
})
|
||||
```
|
||||
|
||||
#### Commit Strategy
|
||||
|
||||
1. **After Test Development** (Phase 4):
|
||||
```bash
|
||||
git add <test_files>
|
||||
git commit -m "test(integration): generate integration tests for ${module}"
|
||||
```
|
||||
|
||||
2. **After Successful Iteration** (pass rate increased):
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "test(integration): iteration ${N} - ${strategy} (pass: ${oldRate}% → ${newRate}%)"
|
||||
```
|
||||
|
||||
3. **Before Rollback** (regression detected):
|
||||
```bash
|
||||
git revert HEAD
|
||||
git commit -m "test(integration): rollback iteration ${N} - regression detected"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 6: Completion
|
||||
|
||||
**Objective**: Finalize reflection log, update state summary, offer next steps.
|
||||
|
||||
**Workflow Steps**:
|
||||
|
||||
1. **Update state.json** — write `summary` field:
|
||||
|
||||
```json
|
||||
{
|
||||
"summary": {
|
||||
"result": "success|partial_success|failure",
|
||||
"final_pass_rate": 0,
|
||||
"total_iterations": 0,
|
||||
"strategies_used": [],
|
||||
"test_metrics": {
|
||||
"total_tests": 0,
|
||||
"passed": 0,
|
||||
"failed": 0,
|
||||
"test_files": 0,
|
||||
"integration_points_covered": 0
|
||||
},
|
||||
"key_learnings": [],
|
||||
"corrected_assumptions": [],
|
||||
"recommendations": [],
|
||||
"completed": "{timestamp}"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Also set `state.json.phase` to `"completed"`.
|
||||
|
||||
2. **Finalize reflection-log.md** — replace `## Conclusions` placeholder:
|
||||
|
||||
```markdown
|
||||
## Conclusions - {timestamp}
|
||||
|
||||
### Result: {SUCCESS|PARTIAL SUCCESS|NEEDS ATTENTION}
|
||||
|
||||
### Metrics
|
||||
- **Final Pass Rate**: {X}%
|
||||
- **Total Iterations**: {N}
|
||||
- **Strategies Used**: {list}
|
||||
- **Tests**: {passed}/{total} across {N} files
|
||||
|
||||
### What We Established
|
||||
- {verified integration behavior}
|
||||
|
||||
### What Was Corrected
|
||||
- ~~{old assumption}~~ → {corrected understanding}
|
||||
|
||||
### Key Insights
|
||||
- {insight with impact on future testing}
|
||||
|
||||
### Decision Trail
|
||||
| Phase/Iteration | Decision | Outcome |
|
||||
|-----------------|----------|---------|
|
||||
| Exploration | Focus on {boundaries} | Found {N} integration points |
|
||||
| Iteration 1 | Conservative single fix | Pass rate: {X}% |
|
||||
| ... | ... | ... |
|
||||
|
||||
### Recommendations
|
||||
- {codebase improvement}
|
||||
- {test maintenance}
|
||||
```
|
||||
|
||||
3. **Post-Completion Options** (AskUserQuestion)
|
||||
|
||||
```javascript
|
||||
AskUserQuestion({
|
||||
questions: [{
|
||||
question: "集成测试完成，下一步？",
|
||||
header: "Next Steps",
|
||||
options: [
|
||||
{ label: "创建Issue", description: "将发现的问题创建为Issue跟踪" },
|
||||
{ label: "扩展测试", description: "基于当前测试继续扩展覆盖范围" },
|
||||
{ label: "生成报告", description: "导出详细测试报告" },
|
||||
{ label: "完成", description: "无需进一步操作" }
|
||||
],
|
||||
multiSelect: false
|
||||
}]
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Completion Conditions
|
||||
|
||||
| Condition | Criteria | Action |
|
||||
|-----------|----------|--------|
|
||||
| **Full Success** | Pass rate === 100% | Finalize with success summary |
|
||||
| **Partial Success** | Pass rate >= 95%, all failures low criticality | Finalize with review notes |
|
||||
| **Failure** | Max iterations reached, pass rate < 95% | Generate failure report with full reflection history |
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Scenario | Action |
|
||||
|----------|--------|
|
||||
| cli-explore-agent fails | Fallback to manual exploration via Grep/Glob |
|
||||
| CLI analysis timeout | Fallback: Gemini → Qwen → Codex → manual |
|
||||
| Test execution crash | Log error, retry with simplified test subset |
|
||||
| Max iterations reached | Generate failure report with full reflection history |
|
||||
| Regression detected | Rollback via git revert, switch to surgical strategy |
|
||||
| Stuck tests (3+ iterations) | Switch to reflective strategy, challenge assumptions |
|
||||
| All CLI tools fail | Pattern match from state.json.fix_history, notify user |
|
||||
|
||||
**CLI Fallback Chain**: Gemini → Qwen → Codex
|
||||
|
||||
Triggers: Invalid JSON output, confidence < 0.4, HTTP 429/timeout, analysis < 100 words, same root cause 3+ times.
|
||||
|
||||
---
|
||||
|
||||
## state.json Full Schema
|
||||
|
||||
Single evolving state file — each phase writes its section:
|
||||
|
||||
```json
|
||||
{
|
||||
"session_id": "ITG-xxx",
|
||||
"module": "description",
|
||||
"started": "timestamp",
|
||||
"max_iterations": 10,
|
||||
"phase": "init|explored|designed|developed|iterating|completed",
|
||||
|
||||
"exploration": {
|
||||
"module_structure": { "entry_points": [], "public_apis": [], "internal_modules": [] },
|
||||
"dependencies": { "upstream": [], "downstream": [], "external_services": [] },
|
||||
"integration_points": [{ "from": "", "to": "", "type": "", "contract": "" }],
|
||||
"data_flows": [{ "name": "", "path": [], "transforms": [] }],
|
||||
"existing_tests": { "test_files": [], "patterns": [], "utilities": [], "mocking_conventions": "" },
|
||||
"test_framework": { "runner": "", "assertion_lib": "", "mock_lib": "" },
|
||||
"risk_areas": [{ "area": "", "reason": "", "priority": "" }],
|
||||
"_metadata": { "files_analyzed": 0, "timestamp": "" }
|
||||
},
|
||||
|
||||
"test_design": {
|
||||
"integration_scenarios": [{ "id": "", "name": "", "boundary": "", "type": "", "priority": "", "test_cases": [], "mocking": {}, "setup": "", "teardown": "" }],
|
||||
"mocking_strategy": { "approach": "", "mock_boundaries": [], "real_boundaries": [], "rationale": "" },
|
||||
"execution_order": [],
|
||||
"success_criteria": { "pass_rate": 95, "coverage_target": 80 }
|
||||
},
|
||||
|
||||
"test_inventory": {
|
||||
"test_files": [{ "path": "", "scenario_ids": [], "test_count": 0, "boundary": "" }],
|
||||
"total_tests": 0,
|
||||
"total_files": 0,
|
||||
"timestamp": ""
|
||||
},
|
||||
|
||||
"iterations": {
|
||||
"current": 0,
|
||||
"strategy": null,
|
||||
"next_action": "execute_tests|execute_fix|complete",
|
||||
"history": [{ "iteration": 0, "pass_rate": 0, "strategy": "", "failed_tests": [], "reflection_summary": "", "strategy_adjustment": "" }],
|
||||
"stuck_tests": [],
|
||||
"latest_results": { "pass_rate": 0, "passed": 0, "failed": 0, "total": 0, "failures": [] }
|
||||
},
|
||||
|
||||
"fix_history": [{ "iteration": 0, "strategy": "", "modification_points": [], "affected_tests": [], "confidence": 0.0 }],
|
||||
|
||||
"summary": {
|
||||
"result": "success|partial_success|failure",
|
||||
"final_pass_rate": 0,
|
||||
"total_iterations": 0,
|
||||
"strategies_used": [],
|
||||
"test_metrics": {},
|
||||
"key_learnings": [],
|
||||
"corrected_assumptions": [],
|
||||
"recommendations": [],
|
||||
"completed": ""
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Clear Module Description**: Specific module names improve exploration quality
|
||||
2. **Trust the Reflection**: Cumulative learnings inform better strategy choices over time
|
||||
3. **Monitor reflection-log.md**: The single document captures the full journey
|
||||
4. **Auto Mode for CI**: Use `-y` for automated pipelines
|
||||
5. **Start Conservative**: Let the strategy engine escalate naturally
|
||||
6. **Review Stuck Tests**: 3+ iterations means test design may need revisiting
|
||||
7. **Incremental Commits**: Each iteration is a safe rollback point
|
||||
|
||||
---
|
||||
|
||||
## Usage Recommendations
|
||||
|
||||
**Use this command when:**
|
||||
- Starting integration tests from scratch for a module
|
||||
- Need comprehensive exploration before test development
|
||||
- Want self-healing test cycles with documented reasoning
|
||||
|
||||
**Use `/workflow:test-fix-gen` + `/workflow:test-cycle-execute` when:**
|
||||
- Already have a completed implementation session (WFS-*)
|
||||
- Only need unit/component level tests
|
||||
|
||||
**Use `/workflow:tdd-plan` when:**
|
||||
- Building new features with test-first approach
|
||||
- Red-Green-Refactor cycle
|
||||
|
||||
---
|
||||
|
||||
**Now execute integration-test-cycle for**: $ARGUMENTS
|
||||
850
.claude/commands/workflow/refactor-cycle.md
Normal file
850
.claude/commands/workflow/refactor-cycle.md
Normal file
@@ -0,0 +1,850 @@
|
||||
---
|
||||
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(*), 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
|
||||
|
||||
```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
|
||||
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**
|
||||
|
||||
```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
|
||||
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
|
||||
|
||||
```javascript
|
||||
// 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
|
||||
|
||||
```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-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
|
||||
Reference in New Issue
Block a user