refining

name	refining
version	1.0.0
status	implemented
description	迭代精炼阶段 - 固化"发现问题→分析问题→修改错误"的反馈循环 用于检测、诊断和修复工作流中的问题和错误
tags	["phase","feedback","iteration"]
requires	{"tools":["Read","Write","Grep","Glob","Bash","Agent"]}

REFINING

Preamble

{{include: ../_shared/preamble.md}}

Overview

REFINING 阶段是 agentic-workflow 的反馈循环核心，用于：

• 发现问题：通过验证、审查、测试发现当前方案的问题
• 分析问题：诊断问题的根本原因和影响范围
• 修改错误：制定修复方案并执行
• 验证结果：确认修复有效，防止回退

触发条件

满足以下任一条件时进入 REFINING 阶段：

1. 主动触发 - 用户请求迭代、改进、优化、精炼
2. 被动触发 - 其他阶段发现无法解决的问题
3. 自动触发 - 审查/测试发现严重问题
4. 命令触发 - /refining 或 /iterate

反馈循环状态机

┌─────────────────────────────────────────────────────────────────┐
│                      FEEDBACK LOOP                               │
│                                                                 │
│   ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐│
│   │ DISCOVER │───▶│ ANALYZE  │───▶│   FIX    │───▶│ VERIFY   ││
│   └──────────┘    └──────────┘    └──────────┘    └──────────┘│
│        │                                               │       │
│        │              LOOP UNTIL                        │       │
│        └───────────────────────────────────────────────┘       │
│                      (问题已修复)                                │
└─────────────────────────────────────────────────────────────────┘

Core Process

Step 1: DISCOVER - 发现问题

任务：识别当前方案中的问题

检查清单：

□ 一致性检查：方案内部是否自洽？
□ 完整性检查：是否覆盖所有边界情况？
□ 可行性检查：技术实现是否可行？
□ 性能检查：是否存在性能瓶颈？
□ 用户反馈：是否符合用户预期？
□ 测试结果：是否有测试失败？
□ 审查意见：是否有未解决的审查问题？

问题分类：

类别	描述	示例
consistency	一致性问题	大纲前后矛盾、设定冲突
completeness	完整性问题	缺少边界情况处理
feasibility	可行性问题	技术无法实现
performance	性能问题	速度慢、资源消耗大
quality	质量问题	代码不规范、文档缺失
alignment	对齐问题	与用户预期不符

问题严重程度：

级别	描述	影响	处理方式
P0_CRITICAL	致命问题	阻断性问题，无法继续	立即修复
P1_HIGH	高优先级	影响核心功能	优先修复
P2_MEDIUM	中优先级	影响体验	计划修复
P3_LOW	低优先级	边缘问题	后续处理

输出格式：

## DISCOVER: 问题发现

### 发现的问题

| ID | 问题 | 类别 | 严重程度 | 来源 |
|----|------|------|----------|------|
| ISSUE-001 | xxx | consistency | P1_HIGH | 审查 |
| ISSUE-002 | xxx | completeness | P2_MEDIUM | 用户反馈 |

### 问题摘要

- P0_CRITICAL: 0
- P1_HIGH: 1
- P2_MEDIUM: 1
- P3_LOW: 0

### 是否需要进入修复阶段？

YES - 发现 P0/P1 问题，需要修复
NO - 仅有 P3 问题，可延迟处理

Step 2: ANALYZE - 分析问题

任务：诊断问题的根本原因

分析框架：

5-Why 分析法：
问题：xxx
为什么1：xxx
为什么2：xxx
为什么3：xxx
为什么4：xxx
为什么5：xxx
根本原因：xxx

影响范围分析：
- 受影响的文件/模块
- 受影响的用户场景
- 回退风险

分析报告模板：

## ANALYZE: 问题分析

### ISSUE-001: xxx

**问题描述**：
xxx

**根本原因**：
xxx

**影响范围**：
- 受影响文件：xxx
- 受影响功能：xxx
- 用户影响：xxx

**修复约束**：
- 时间约束：xxx
- 技术约束：xxx
- 风险约束：xxx

**可选方案**：

| 方案 | 优点 | 缺点 | 成本 |
|------|------|------|------|
| A | xxx | xxx | 高 |
| B | xxx | xxx | 低 |

**推荐方案**：B（成本最低，效果相当）

Step 3: FIX - 修改错误

任务：执行修复方案

修复执行清单：

□ 创建修复分支（如果需要）
□ 备份原始文件
□ 执行修复
□ 更新相关文档
□ 更新测试用例
□ 验证修复
□ 提交更改

修复执行报告：

## FIX: 修复执行

### 已修复问题

| ID | 问题 | 修复方案 | 修复文件 |
|----|------|----------|----------|
| ISSUE-001 | xxx | 方案B | file1.md, file2.md |

### 修复详情

**ISSUE-001 修复**：
- 修复前：xxx
- 修复后：xxx
- 修复方法：xxx

### 残留问题

| ID | 问题 | 处理方式 | 计划修复时间 |
|----|------|----------|--------------|
| ISSUE-002 | xxx | 延迟处理 | 下个迭代 |

### 变更清单

- modified: file1.md
- modified: file2.md
- created: file3.md

Step 4: VERIFY - 验证结果

任务：确认修复有效

验证检查清单：

□ 问题已修复：原问题不再存在
□ 没有引入新问题：修复没有破坏其他功能
□ 测试通过：相关测试全部通过
□ 文档已更新：相关文档已同步更新
□ 用户确认：用户认可修复结果（如果适用）

验证报告：

## VERIFY: 验证结果

### 修复验证

| ID | 问题 | 验证结果 | 验证方法 |
|----|------|----------|----------|
| ISSUE-001 | xxx | PASS | 重现测试 |

### 回归测试

- [x] 没有引入新的问题
- [x] 相关功能正常
- [x] 文档已同步

### 迭代结论

**状态**：COMPLETE - 所有 P0/P1 问题已修复

**残留问题**：1 个 P3 问题，延迟处理

**是否可以进入下一阶段**：YES

反馈循环协议

循环终止条件

满足以下任一条件时，终止反馈循环：

1. 完全修复：所有 P0/P1 问题已修复
2. 用户满意：用户确认当前方案可接受
3. 资源耗尽：达到最大迭代次数（默认3次）
4. 不可修复：问题在当前约束下无法修复

循环次数限制

问题严重程度	最大迭代次数
P0_CRITICAL	5次
P1_HIGH	3次
P2_MEDIUM	2次
P3_LOW	1次

问题升级协议

如果迭代达到最大次数但问题未解决：

IF 迭代次数 >= 最大限制 AND 问题仍存在 THEN
    IF 问题严重程度 == P0_CRITICAL THEN
        升级到用户，要求立即处理
    ELSE
        记录为技术债务，后续处理
        继续下一阶段
    END
END

与其他阶段的集成

从 REVIEWING 进入 REFINING

REVIEWING 发现问题 → REFINING(DISCOVER) → 分析修复 → VERIFY

从 EXECUTING 进入 REFINING

EXECUTING 遇到障碍 → REFINING(ANALYZE) → 诊断问题 → 回到 EXECUTING

从 PLANNING 进入 REFINING

PLANNING 发现冲突 → REFINING(DISCOVER) → 解决冲突 → 继续 PLANNING

输出文件

REFINING 阶段生成以下文件：

文件	内容	位置
refining_report.md	完整反馈循环报告	项目根目录
issues.md	问题跟踪清单	项目根目录

Completion Status Protocol

DONE

所有问题已修复，验证通过。

[REFINING] DONE
- issues_fixed: [ISSUE-001, ISSUE-002]
- issues_deferred: [ISSUE-003]
- iterations: 2

DONE_WITH_DEBT

问题已修复，但存在技术债务。

[REFINING] DONE_WITH_DEBT
- issues_fixed: [ISSUE-001]
- technical_debt: [ISSUE-002]
- debt_reason: 修复成本过高，推迟处理

BLOCKED

遇到无法修复的问题，需要升级。

[REFINING] BLOCKED
- blocker: ISSUE-001
- reason: 达到最大迭代次数，问题仍存在
- action: 升级到用户

NEEDS_ESCALATION

需要用户决策或额外资源。

[REFINING] NEEDS_ESCALATION
- question: xxx
- options: [A, B, C]
- impact: 如果不处理，将导致 xxx

铁律

1. 不掩盖问题：发现问题必须记录和修复，不能忽略
2. 穷尽分析：没有分析清楚根本原因之前，不开始修复
3. 小步快跑：每次修复尽量小，便于验证和回退
4. 验证为王：修复后必须验证，不能假设修复有效