fix-issue

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Fix Issue

修复问题

Systematic issue resolution with hypothesis-based root cause analysis, similar issue detection, and prevention recommendations.

基于假设的根本原因分析、相似问题检测及预防建议的系统化问题解决流程。

Quick Start

快速开始

bash

/ork:fix-issue 123
/ork:fix-issue 456

Opus 4.6: Root cause analysis uses native adaptive thinking. Dynamic token budgets scale with context window for thorough investigation.

bash

/ork:fix-issue 123
/ork:fix-issue 456

Opus 4.6：根本原因分析采用原生自适应思维。动态token预算会根据上下文窗口调整，以实现全面调查。

Overview

概述

Systematic issue resolution with hypothesis-based root cause analysis. Uses parallel agents to investigate similar issues, form hypotheses, and validate fixes. Includes prevention recommendations and lessons learned capture to break recurring issue cycles.

基于假设的根本原因分析的系统化问题解决流程。使用并行Agent调查相似问题、形成假设并验证修复方案。包含预防建议和经验总结，以打破问题重复出现的循环。

STEP 0: Verify User Intent with AskUserQuestion

步骤0：通过AskUserQuestion验证用户意图

BEFORE creating tasks, clarify fix approach:

python

AskUserQuestion(
  questions=[{
    "question": "What approach for this fix?",
    "header": "Approach",
    "options": [
      {"label": "Proper fix (Recommended)", "description": "Full RCA, tests, prevention recommendations"},
      {"label": "Quick fix", "description": "Minimal fix to resolve the immediate issue"},
      {"label": "Investigate first", "description": "Understand the issue before deciding on approach"},
      {"label": "Hotfix", "description": "Emergency patch, minimal testing"}
    ],
    "multiSelect": false
  }]
)

Based on answer, adjust workflow:

Proper fix: All 11 phases, parallel agents for RCA
Quick fix: Skip phases 8-10 (prevention, runbook, lessons)
Investigate first: Only phases 1-4 (understand, search, hypotheses, analyze)
Hotfix: Minimal phases, skip similar issue search

在创建任务之前，明确修复方式：

python

AskUserQuestion(
  questions=[{
    "question": "What approach for this fix?",
    "header": "Approach",
    "options": [
      {"label": "Proper fix (Recommended)", "description": "Full RCA, tests, prevention recommendations"},
      {"label": "Quick fix", "description": "Minimal fix to resolve the immediate issue"},
      {"label": "Investigate first", "description": "Understand the issue before deciding on approach"},
      {"label": "Hotfix", "description": "Emergency patch, minimal testing"}
    ],
    "multiSelect": false
  }]
)

根据回答调整工作流：

标准修复：执行全部11个阶段，使用并行Agent进行根本原因分析（RCA）
快速修复：跳过第8-10阶段（预防措施、操作手册、经验总结）
先调查：仅执行第1-4阶段（理解问题、搜索相似问题、形成假设、分析原因）
紧急修复：仅执行最少阶段，跳过相似问题搜索

STEP 0b: Select Orchestration Mode

步骤0b：选择编排模式

Choose Agent Teams (mesh — RCA agents share hypotheses) or Task tool (star — all report to lead):

```
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
```
→ Agent Teams mode
Agent Teams unavailable → Task tool mode (default)
Otherwise: Complex cross-cutting bugs (backend + frontend + tests involved) → recommend Agent Teams; Focused bugs (single domain) → Task tool

Aspect	Task Tool	Agent Teams
Hypothesis sharing	Lead relays between agents	Investigators share hypotheses in real-time
Conflicting evidence	Lead resolves	Investigators debate directly
Cost	~250K tokens	~600K tokens
Best for	Single-domain bugs	Cross-cutting bugs with multiple hypotheses

Fallback: If Agent Teams encounters issues, fall back to Task tool for remaining investigation.

选择Agent Teams（网状结构 — RCA Agent共享假设）或任务工具（星型结构 — 所有Agent向主导者汇报）：

```
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
```
→ Agent Teams模式
若Agent Teams不可用 → 任务工具模式（默认）
其他情况：复杂跨域漏洞（涉及后端+前端+测试）→ 推荐Agent Teams；聚焦型漏洞（单一领域）→ 任务工具

维度	任务工具	Agent Teams
假设共享	主导者在Agent间传递信息	调查者实时共享假设
冲突证据处理	主导者解决	调查者直接讨论
成本	~250K tokens	~600K tokens
适用场景	单一领域漏洞	存在多种假设的跨域漏洞

降级方案：若Agent Teams出现问题，剩余调查流程切换为任务工具模式。

Task Management (CC 2.1.16)

任务管理（CC 2.1.16）

python

undefined

python

undefined

Create main fix task

创建主修复任务

TaskCreate( subject="Fix issue #{number}", description="Systematic issue resolution with hypothesis-based RCA", activeForm="Fixing issue #{number}" )

Create subtasks for 11-phase process

为11阶段流程创建子任务

phases = ["Understand issue", "Search similar issues", "Form hypotheses", "Analyze root cause", "Design fix", "Implement fix", "Validate fix", "Generate prevention", "Create runbook", "Capture lessons", "Commit and PR"] for phase in phases: TaskCreate(subject=phase, activeForm=f"{phase}ing")

---

---

Workflow Overview

工作流概述

Phase	Activities	Output
1. Understand Issue	Read GitHub issue details	Problem statement
2. Similar Issue Detection	Search for related past issues	Related issues list
3. Hypothesis Formation	Form hypotheses with confidence scores	Ranked hypotheses
4. Root Cause Analysis	5 parallel agents investigate	Confirmed root cause
5. Fix Design	Design approach based on RCA	Fix specification
6. Implementation	Apply fix with tests	Working code
7. Validation	Verify fix resolves issue	Evidence
8. Prevention	How to prevent recurrence	Prevention plan
9. Runbook	Create/update runbook entry	Runbook
10. Lessons Learned	Capture knowledge	Persisted learnings
11. Commit and PR	Create PR with fix	Merged PR

阶段	活动	输出
1. 理解问题	查看GitHub问题详情	问题描述
2. 相似问题检测	搜索过往相关问题	相关问题列表
3. 形成假设	生成带置信度评分的假设	排序后的假设
4. 根本原因分析	5个并行Agent开展调查	确认的根本原因
5. 修复方案设计	基于RCA设计修复方案	修复规格说明
6. 实施修复	应用修复并添加测试	可运行代码
7. 验证修复	验证修复是否解决问题	验证证据
8. 生成预防措施	如何防止问题复发	预防计划
9. 创建操作手册	创建/更新操作手册条目	操作手册
10. 经验总结	留存知识	持久化经验
11. 提交与PR	创建包含修复内容的PR	已合并的PR

Phase 1: Understand the Issue

阶段1：理解问题

bash

gh issue view $ARGUMENTS --json title,body,labels,assignees,comments
gh pr list --search "issue:$ARGUMENTS"
gh issue view $ARGUMENTS --comments

Start Work ceremony (from

issue-progress-tracking

): move issue to in-progress, comment on issue, ensure branch is named

issue/N-description

bash

gh issue view $ARGUMENTS --json title,body,labels,assignees,comments
gh pr list --search "issue:$ARGUMENTS"
gh issue view $ARGUMENTS --comments

启动工作仪式（来自

issue-progress-tracking

）：将问题移至“进行中”状态，在问题下添加评论，确保分支命名为

issue/N-description

。

Phase 2: Similar Issue Detection

阶段2：相似问题检测

See Similar Issue Search for patterns.

bash

gh issue list --search "[key error message]" --state all
mcp__memory__search_nodes(query="issue [error type] fix")

Similar Issue	Similarity	Status	Relevant?
#101	85%	Closed	Yes

Determine: Regression? Variant? New issue?

相似问题搜索模式请参考Similar Issue Search。

bash

gh issue list --search "[key error message]" --state all
mcp__memory__search_nodes(query="issue [error type] fix")

相似问题	相似度	状态	是否相关
#101	85%	已关闭	是

判断：是否为回归问题？变体问题？新问题？

Phase 3: Hypothesis Formation

阶段3：形成假设

See Hypothesis-Based RCA for confidence scoring.

markdown

undefined

置信度评分规则请参考Hypothesis-Based RCA。

markdown

undefined

Hypothesis 1: [Brief name]

假设1：[简短名称]

Confidence: [0-100]% Description: [What might cause the issue] Test: [How to verify]


| Confidence | Meaning |
|------------|---------|
| 90-100% | Near certain |
| 70-89% | Highly likely |
| 50-69% | Probable |
| 30-49% | Possible |
| 0-29% | Unlikely |

---

置信度：[0-100]% 描述：[可能导致问题的原因] 测试方法：[验证方式]


| 置信度 | 含义 |
|------------|---------|
| 90-100% | 几乎确定 |
| 70-89% | 极有可能 |
| 50-69% | 可能 |
| 30-49% | 有可能 |
| 0-29% | 不太可能 |

---

Phase 4: Root Cause Analysis (5 Agents)

阶段4：根本原因分析（5个Agent）

Launch ALL 5 agents in parallel with

run_in_background=True

and

max_turns=25

debug-investigator: Root cause tracing
debug-investigator: Impact analysis
backend-system-architect: Backend fix design
frontend-ui-developer: Frontend fix design
test-generator: Test requirements

Each agent outputs structured JSON with findings and SUMMARY line.

以

run_in_background=True

和

max_turns=25

参数并行启动全部5个Agent：

debug-investigator：根本原因追踪
debug-investigator：影响分析
backend-system-architect：后端修复方案设计
frontend-ui-developer：前端修复方案设计
test-generator：测试需求制定

每个Agent输出包含调查结果和SUMMARY行的结构化JSON。

Phase 4 — Agent Teams Alternative

阶段4 — Agent Teams替代方案

See references/agent-teams-rca.md for Agent Teams root cause analysis workflow.

Agent Teams根本原因分析工作流请参考references/agent-teams-rca.md。

Phase 5: Fix Design

阶段5：修复方案设计

markdown

undefined

markdown

undefined

Fix Design for Issue #$ARGUMENTS

问题#$ARGUMENTS的修复方案

Root Cause (Confirmed)

确认的根本原因

[Description]

[描述]

Proposed Fix

提议的修复方案

[Approach]

[实现思路]

Files to Modify

需修改的文件

File	Change	Reason
[file]	MODIFY	[why]

文件	变更	原因
[file]	MODIFY	[原因]

Risks

风险

[Risk 1]

[风险1]

Rollback Plan

回滚计划

[How to revert]

---

[回滚方式]

---

Phase 6: Implementation

阶段6：实施修复

CRITICAL: Feature Branch Required

关键要求：必须使用功能分支

NEVER commit directly to main or dev. Always create a feature branch:

bash

undefined

绝对禁止直接提交到main或dev分支。务必创建功能分支：

bash

undefined

Determine base branch

确定基准分支

BASE_BRANCH=$(git remote show origin | grep 'HEAD branch' | cut -d: -f2 | tr -d ' ')

Create feature branch (MANDATORY)

创建功能分支（强制要求）

git checkout $BASE_BRANCH && git pull origin $BASE_BRANCH git checkout -b issue/$ARGUMENTS-fix

undefined

git checkout $BASE_BRANCH && git pull origin $BASE_BRANCH git checkout -b issue/$ARGUMENTS-fix

undefined

CRITICAL: Regression Test Required

关键要求：必须添加回归测试

A fix without a test is incomplete. Add test BEFORE implementing fix:

bash

undefined

没有测试的修复是不完整的。在实施修复前先添加测试：

bash

undefined

1. Write test that reproduces the bug (should FAIL)

1. 编写可复现漏洞的测试（应执行失败）

2. Implement the fix

2. 实施修复

3. Verify test now PASSES

3. 验证测试现在执行通过


**Guidelines:**
- Make minimal, focused changes
- Add proper error handling
- Add regression test FIRST (MANDATORY)
- DO NOT over-engineer
- DO NOT commit directly to protected branches

---

undefined

Phase 7: Validation

准则：

bash

undefined

仅做最小化、聚焦性变更
添加适当的错误处理
先添加回归测试（强制要求）
不要过度设计
不要直接提交到受保护分支

Backend

阶段7：验证修复

poetry run ruff format --check app/ poetry run pytest tests/unit/ -v --tb=short

bash

undefined

Frontend

后端

npm run lint && npm run typecheck && npm run test

---

poetry run ruff format --check app/ poetry run pytest tests/unit/ -v --tb=short

Phase 8: Prevention Recommendations

前端

CRITICAL: Prevention must include at least one of:

Automated test - CI catches similar issues (PREFERRED)
Validation rule - Schema/lint rule prevents bad state
Process check - Review checklist item

See Prevention Patterns for full template.

Category	Examples	Effectiveness
Automated test	Unit/integration test in CI	HIGH - catches before merge
Validation rule	Schema check, lint rule	HIGH - catches on save/commit
Architecture	Better error boundaries	MEDIUM
Process	Review checklist item	LOW - human-dependent

npm run lint && npm run typecheck && npm run test

---

Phase 9: Runbook Generation

阶段8：预防建议

markdown

undefined

关键要求：预防措施必须包含至少一项：

自动化测试 - CI捕获相似问题（首选）
验证规则 - Schema/ lint规则防止不良状态
流程检查 - 评审检查项

完整模板请参考Prevention Patterns。

类别	示例	有效性
自动化测试	CI中的单元/集成测试	高 - 合并前捕获问题
验证规则	Schema检查、Lint规则	高 - 保存/提交时捕获问题
架构优化	更完善的错误边界	中
流程优化	评审检查项	低 - 依赖人工

Runbook: [Issue Type]

阶段9：生成操作手册

Symptoms

—

[Observable symptom]

markdown

undefined

Diagnosis Steps

操作手册：[问题类型]

—

症状

Check [X] by running:
```
[command]
```

[可观察到的症状]

Resolution Steps

诊断步骤

[Step 1]

通过执行以下命令检查[X]：
```
[command]
```

Prevention

解决步骤

[How to prevent]


Store in memory for future reference.

---

[步骤1]

Phase 10: Lessons Learned

预防措施

python

mcp__memory__create_entities(entities=[{
  "name": "lessons-issue-$ARGUMENTS",
  "entityType": "LessonsLearned",
  "observations": [
    "root_cause: [brief]",
    "key_learning: [most important]",
    "prevention: [recommendation]"
  ]
}])

[预防方式]


存储至内存供未来参考。

---

Phase 11: Commit and PR

阶段10：经验总结

bash

git add .
git commit -m "fix(#$ARGUMENTS): [Brief description]

Root cause: [one line]
Prevention: [recommendation]"

git push -u origin issue/$ARGUMENTS-fix
gh pr create --base dev --title "fix(#$ARGUMENTS): [description]"

python

mcp__memory__create_entities(entities=[{
  "name": "lessons-issue-$ARGUMENTS",
  "entityType": "LessonsLearned",
  "observations": [
    "root_cause: [brief]",
    "key_learning: [most important]",
    "prevention: [recommendation]"
  ]
}])

Key Decisions

阶段11：提交与PR

Decision	Choice	Rationale
Feature branch	MANDATORY	Never commit to main/dev directly
Regression test	MANDATORY	Fix without test is incomplete
Hypothesis confidence	0-100% scale	Quantifies certainty
Similar issue search	Before hypothesis	Leverage past solutions
Prevention analysis	Mandatory phase	Break recurring issue cycle
Runbook generation	Template-based	Consistent documentation

bash

git add .
git commit -m "fix(#$ARGUMENTS): [Brief description]

Root cause: [one line]
Prevention: [recommendation]"

git push -u origin issue/$ARGUMENTS-fix
gh pr create --base dev --title "fix(#$ARGUMENTS): [description]"

CC 2.1.49 Enhancements

关键决策

See references/cc-enhancements.md for session resume, task metrics, tool guidance, worktree isolation, and adaptive thinking.

决策	选择	理由
功能分支	强制要求	禁止直接提交到main/dev分支
回归测试	强制要求	没有测试的修复是不完整的
假设置信度	0-100%评分体系	量化确定性
相似问题搜索	在形成假设前执行	借鉴过往解决方案
预防分析	强制阶段	打破问题重复出现的循环
操作手册生成	基于模板	确保文档一致性

Rules Quick Reference

CC 2.1.49 增强功能

Rule	Impact	What It Covers
rca-five-whys	HIGH	5 Whys iterative causal analysis
rca-fishbone	MEDIUM	Ishikawa diagram, multi-factor analysis
rca-fault-tree	MEDIUM	Fault tree analysis, AND/OR gates, critical systems

会话恢复、任务指标、工具指引、工作区隔离及自适应思维相关内容请参考references/cc-enhancements.md。

Related Skills

规则速查

```
ork:commit
```
- Commit issue fixes
```
debug-investigator
```
- Debug complex issues
```
ork:issue-progress-tracking
```
- Auto-updates from commits
```
ork:remember
```
- Store lessons learned

Version: 2.1.0 (February 2026)

规则	影响	覆盖范围
rca-five-whys	高	5Why迭代因果分析
rca-fishbone	中	鱼骨图、多因素分析
rca-fault-tree	中	故障树分析、AND/OR门、关键系统

—