Back to Details

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):
  1. CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
    → Agent Teams mode
  2. Agent Teams unavailable → Task tool mode (default)
  3. Otherwise: Complex cross-cutting bugs (backend + frontend + tests involved) → recommend Agent Teams; Focused bugs (single domain) → Task tool
AspectTask ToolAgent Teams
Hypothesis sharingLead relays between agentsInvestigators share hypotheses in real-time
Conflicting evidenceLead resolvesInvestigators debate directly
Cost~250K tokens~600K tokens
Best forSingle-domain bugsCross-cutting bugs with multiple hypotheses
Fallback: If Agent Teams encounters issues, fall back to Task tool for remaining investigation.
选择Agent Teams（网状结构 — RCA Agent共享假设）或任务工具（星型结构 — 所有Agent向主导者汇报）：
  1. CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
    → Agent Teams模式
  2. 若Agent Teams不可用 → 任务工具模式（默认）
  3. 其他情况：复杂跨域漏洞（涉及后端+前端+测试）→ 推荐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}" )
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")

---
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

工作流概述

PhaseActivitiesOutput
1. Understand IssueRead GitHub issue detailsProblem statement
2. Similar Issue DetectionSearch for related past issuesRelated issues list
3. Hypothesis FormationForm hypotheses with confidence scoresRanked hypotheses
4. Root Cause Analysis5 parallel agents investigateConfirmed root cause
5. Fix DesignDesign approach based on RCAFix specification
6. ImplementationApply fix with testsWorking code
7. ValidationVerify fix resolves issueEvidence
8. PreventionHow to prevent recurrencePrevention plan
9. RunbookCreate/update runbook entryRunbook
10. Lessons LearnedCapture knowledgePersisted learnings
11. Commit and PRCreate PR with fixMerged 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 IssueSimilarityStatusRelevant?
#10185%ClosedYes
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")
相似问题相似度状态是否相关
#10185%已关闭是
判断：是否为回归问题？变体问题？新问题？

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
:
  1. debug-investigator: Root cause tracing
  2. debug-investigator: Impact analysis
  3. backend-system-architect: Backend fix design
  4. frontend-ui-developer: Frontend fix design
  5. test-generator: Test requirements
Each agent outputs structured JSON with findings and SUMMARY line.
以
run_in_background=True
和
max_turns=25
参数并行启动全部5个Agent：
  1. debug-investigator：根本原因追踪
  2. debug-investigator：影响分析
  3. backend-system-architect：后端修复方案设计
  4. frontend-ui-developer：前端修复方案设计
  5. 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

需修改的文件

FileChangeReason
[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 ' ')
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:
  1. Automated test - CI catches similar issues (PREFERRED)
  2. Validation rule - Schema/lint rule prevents bad state
  3. Process check - Review checklist item
See Prevention Patterns for full template.
CategoryExamplesEffectiveness
Automated testUnit/integration test in CIHIGH - catches before merge
Validation ruleSchema check, lint ruleHIGH - catches on save/commit
ArchitectureBetter error boundariesMEDIUM
ProcessReview checklist itemLOW - human-dependent
npm run lint && npm run typecheck && npm run test

---

Phase 9: Runbook Generation

阶段8：预防建议

markdown
undefined
关键要求：预防措施必须包含至少一项：
  1. 自动化测试 - CI捕获相似问题（首选）
  2. 验证规则 - Schema/ lint规则防止不良状态
  3. 流程检查 - 评审检查项
完整模板请参考Prevention Patterns。
类别示例有效性
自动化测试CI中的单元/集成测试高 - 合并前捕获问题
验证规则Schema检查、Lint规则高 - 保存/提交时捕获问题
架构优化更完善的错误边界中
流程优化评审检查项低 - 依赖人工

Runbook: [Issue Type]

阶段9：生成操作手册

Symptoms

—
  • [Observable symptom]
markdown
undefined

Diagnosis Steps

操作手册：[问题类型]

—

症状

  1. Check [X] by running: 
    [command]
  • [可观察到的症状]

Resolution Steps

诊断步骤

  1. [Step 1]
  1. 通过执行以下命令检查[X]：
    [command]

Prevention

解决步骤

  • [How to prevent]

Store in memory for future reference.

---
  1. [步骤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

DecisionChoiceRationale
Feature branchMANDATORYNever commit to main/dev directly
Regression testMANDATORYFix without test is incomplete
Hypothesis confidence0-100% scaleQuantifies certainty
Similar issue searchBefore hypothesisLeverage past solutions
Prevention analysisMandatory phaseBreak recurring issue cycle
Runbook generationTemplate-basedConsistent 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 增强功能

RuleImpactWhat It Covers
rca-five-whysHIGH5 Whys iterative causal analysis
rca-fishboneMEDIUMIshikawa diagram, multi-factor analysis
rca-fault-treeMEDIUMFault 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门、关键系统
—

相关技能

—
  • ork:commit
    - 提交问题修复
  • debug-investigator
    - 调试复杂问题
  • ork:issue-progress-tracking
    - 从提交自动更新状态
  • ork:remember
    - 存储经验总结
版本： 2.1.0（2026年2月）