fix

修复

用于调查和解决 Bug 的工作流编排器。根据问题范围串联专用技能。

用法

/fix <scope> [options] [description]

问题流程（无参数）

如果用户只输入 /fix，没有参数或只提供了部分参数，请引导他们完成以下问题流程。每个阶段都使用 AskUserQuestion。

阶段 0：工作流选择

question: "What would you like to fix?"
header: "Fix type"
options:
  - label: "Help me choose (Recommended)"
    description: "I'll ask questions to pick the right fix workflow"
  - label: "Bug - something is broken"
    description: "Chain: investigate → diagnose → implement → test → commit"
  - label: "Hook - Claude Code hook issue"
    description: "Chain: debug-hooks → hook-developer → implement → test"
  - label: "Dependencies - import/package errors"
    description: "Chain: preflight → research → plan → implement → qlty-check"
  - label: "PR Comments - address reviewer feedback"
    description: "Chain: github-search → research → plan → implement → commit"

映射：

• “帮我选择” → 继续回答阶段 1-4 的问题
• “Bug” → 设置 scope=bug，跳到阶段 2（问题详情）
• “Hook” → 设置 scope=hook，跳到阶段 2（问题详情）
• “依赖项” → 设置 scope=deps，跳到阶段 2（问题详情）
• “PR 评论” → 设置 scope=pr-comments，跳到阶段 2（问题详情）

如果答案不明确（通过“其他”）：

question: "I want to understand what kind of fix you need. Did you mean..."
header: "Clarify"
options:
  - label: "Help me choose"
    description: "Not sure - guide me through questions"
  - label: "Bug - something is broken"
    description: "Code isn't working as expected"
  - label: "Hook - Claude Code hook issue"
    description: "Hooks not firing or producing wrong output"
  - label: "Neither - let me explain differently"
    description: "I'll describe my issue"

阶段 1：问题类型

question: "What kind of issue are you dealing with?"
header: "Issue type"
options:
  - label: "Something is broken/not working"
    description: "Bug in the code"
  - label: "Claude Code hook not firing"
    description: "Hook-specific debugging"
  - label: "Import/dependency errors"
    description: "Package or module issues"
  - label: "Need to address PR feedback"
    description: "Reviewer comments to fix"

映射：

• “出现故障” → bug 范围
• “Hook 未触发” → hook 范围
• “导入错误” → deps 范围
• “PR 反馈” → pr-comments 范围

阶段 2：问题详情

question: "Can you describe the issue?"
header: "Details"
options: []  # Free text - user describes the problem

收集错误消息、意外行为或 PR 链接。

阶段 3：调查深度

question: "How should I investigate?"
header: "Investigation"
options:
  - label: "Diagnose and fix"
    description: "Find the problem and implement a fix"
  - label: "Diagnose only (dry run)"
    description: "Just tell me what's wrong, don't change code"
  - label: "Quick fix"
    description: "I know the issue, just fix it fast"

映射：

• “仅诊断” → --dry-run
• “快速修复” → 跳过调查，直接调用 spark agent

阶段 4：测试与提交

question: "After fixing, should I..."
header: "After fix"
multiSelect: true
options:
  - label: "Write a regression test"
    description: "Prevent this bug from recurring"
  - label: "Commit the fix"
    description: "Create a git commit"
  - label: "Just fix, nothing else"
    description: "I'll handle tests and git"

映射：

• 不需要“回归测试” → --no-test
• 不需要“提交” → --no-commit

执行前摘要

Based on your answers, I'll run:

**Scope:** bug
**Issue:** "Login button not responding on Safari"
**Chain:** sleuth (investigate) → spark (fix) → arbiter (test) → commit
**Options:** (none)

Proceed? [Yes / Adjust settings]

范围

范围	链	说明
bug	debug -> implement_task -> test-driven-development -> commit	通用 Bug 修复工作流
hook	debug-hooks -> hook-developer -> implement_task -> test hook	Hook 专项调试
deps	dependency-preflight -> oracle -> plan-agent -> implement_plan -> qlty-check	依赖项问题
pr-comments	github-search -> research-codebase -> plan-agent -> implement_plan -> commit	处理 PR 反馈

选项

选项	效果
--no-test	跳过回归测试创建
--dry-run	仅诊断，不实施修复
--no-commit	不自动提交修复

工作流

阶段 1：解析参数

# Parse scope and options
SCOPE="${1:-bug}"
NO_TEST=false
DRY_RUN=false
NO_COMMIT=false

for arg in "$@"; do
  case $arg in
    --no-test) NO_TEST=true ;;
    --dry-run) DRY_RUN=true ;;
    --no-commit) NO_COMMIT=true ;;
  esac
done

阶段 2：调查（并行）

启动 sleuth agent 并行调查：

Task(
  subagent_type="sleuth",
  prompt="""
  Investigate this issue in parallel:

  1. **Logs**: Check recent logs for errors
     - Application logs
     - System logs if relevant
     - Build/test output

  2. **Database State** (if applicable):
     - Check for stuck/invalid records
     - Verify schema matches expectations

  3. **Git State**:
     - Recent commits that might relate
     - Uncommitted changes
     - Current branch context

  4. **Runtime State**:
     - Running processes
     - Port conflicts
     - Environment variables

  Issue description: {user_description}

  Return structured findings with evidence.
  """
)

阶段 3：诊断报告

向用户展示调查结果：

## Diagnosis Report

### Scope: {scope}

### Evidence Found

**Logs:**
- [Finding with timestamp/line reference]

**Database:**
- [Finding with table/query reference]

**Git State:**
- [Recent relevant commits]
- [Uncommitted changes]

**Runtime:**
- [Process/port findings]

### Root Cause Analysis

**Primary Hypothesis:** [Most likely cause based on evidence]

**Supporting Evidence:**
1. [Evidence 1]
2. [Evidence 2]

**Alternative Hypotheses:**
- [Alternative 1]: [Why less likely]

### Proposed Fix

**Approach:** [How to fix]

**Files to Modify:**
- `path/to/file.ts:123` - [Change description]

**Risk Assessment:** [Low/Medium/High] - [Why]

---

**Proceed with fix?** (yes/no/modify approach)

阶段 4：人工检查点（诊断）

必须： 实施前等待用户确认。

AskUserQuestion(
  question="Proceed with the proposed fix?",
  options=["yes", "no", "modify"]
)

如果用户说“修改”，收集新要求并更新方案。 如果用户说“不”，创建诊断交接并退出。 如果使用了 --dry-run，在此创建诊断交接并退出。

阶段 4.5：风险评估（事前分析）

诊断获批后、实施前：

对拟议修复进行快速事前分析，以发现风险：

/premortem quick

事前分析的上下文：

premortem:
  mode: quick
  context: "Bug fix for {diagnosis.root_cause}"

  check_for:
    - Will this fix break other functionality?
    - Is rollback possible if fix causes issues?
    - Are there related edge cases not covered?
    - Does the fix match codebase patterns?
    - Any external dependencies affected?

风险决策：

• 没有 HIGH 老虎：继续实施
• 发现 HIGH 老虎：向用户展示以下选项：
  • 接受风险并继续
  • 修改方案以应对风险
  • 研究缓解策略

AskUserQuestion(
  question="Pre-mortem found {n} risks in the proposed fix. Proceed?",
  options=[
    "Accept risks and implement",
    "Modify fix approach",
    "Research mitigations first"
  ]
)

如果用户选择“研究缓解措施”，则针对每项风险并行启动 scout 和 oracle，然后重新展示选项。

阶段 5：实施

根据范围路由到相应的实施技能：

bug 范围：

Task(
  subagent_type="kraken",
  prompt="""
  Implement fix with TDD approach.

  Root cause: {diagnosis.root_cause}
  Files: {diagnosis.files_to_modify}
  Approach: {diagnosis.approach}

  Follow implement_task workflow:
  1. Write failing test that reproduces the bug
  2. Implement minimal fix to pass test
  3. Refactor if needed
  4. Run full test suite
  """
)

hook 范围：

Task(
  subagent_type="kraken",
  prompt="""
  Fix hook issue.

  Root cause: {diagnosis.root_cause}

  Follow hook-developer patterns:
  1. Check hook registration in settings.json
  2. Verify shell wrapper exists and is executable
  3. Test hook manually with mock input
  4. Rebuild if TypeScript source was modified
  5. Verify hook fires correctly
  """
)

deps 范围：

Task(
  subagent_type="kraken",
  prompt="""
  Fix dependency issue.

  Root cause: {diagnosis.root_cause}

  Follow plan-agent workflow:
  1. Research correct dependency versions
  2. Create implementation plan
  3. Update lockfiles
  4. Run dependency-preflight
  5. Run qlty-check
  """
)

pr-comments 范围：

Task(
  subagent_type="kraken",
  prompt="""
  Address PR feedback.

  Comments: {diagnosis.pr_comments}

  Follow plan-agent workflow:
  1. Research codebase for context
  2. Create implementation plan for each comment
  3. Implement changes
  4. Commit with reference to comment
  """
)

阶段 6：回归测试（除非使用 --no-test）

Task(
  subagent_type="kraken",
  prompt="""
  Create regression test for the fix.

  Bug: {original_issue}
  Fix: {implementation_summary}

  Follow test-driven-development:
  1. Write test that would have caught this bug
  2. Verify test fails against pre-fix code (mentally)
  3. Verify test passes against fixed code
  4. Test should be minimal and focused
  """
)

阶段 7：人工检查点（验证）

AskUserQuestion(
  question="Fix implemented. Please verify and confirm.",
  options=["looks good", "needs adjustment", "revert"]
)

如果用户说“需要调整”，收集反馈并返回阶段 5。 如果用户说“回滚”，运行回滚命令并退出。

阶段 8：提交（除非使用 --no-commit）

Task(
  subagent_type="general-purpose",
  prompt="""
  Follow commit skill:

  1. Review changes with git diff
  2. Create descriptive commit message
  3. Reference issue/ticket if applicable
  4. Present plan and await confirmation
  5. Execute commit
  """
)

各范围的链详情

bug

sleuth (investigation)
  |
  v
[HUMAN CHECKPOINT: diagnosis]
  |
  v
[PREMORTEM: quick risk check]
  |
  v
kraken (implement_task + TDD)
  |
  v
kraken (regression test)
  |
  v
[HUMAN CHECKPOINT: verification]
  |
  v
commit

hook

debug-hooks (structured investigation)
  |
  v
[HUMAN CHECKPOINT: diagnosis]
  |
  v
[PREMORTEM: quick risk check]
  |
  v
kraken (implement_task + hook-developer patterns)
  |
  v
test hook manually
  |
  v
[HUMAN CHECKPOINT: verification]
  |
  v
commit

deps

dependency-preflight (check current state)
  |
  v
oracle (find correct versions/alternatives)
  |
  v
plan-agent (create fix plan)
  |
  v
[HUMAN CHECKPOINT: diagnosis + plan review]
  |
  v
[PREMORTEM: quick risk check]
  |
  v
kraken (implement_plan)
  |
  v
qlty-check
  |
  v
[HUMAN CHECKPOINT: verification]
  |
  v
commit

pr-comments

github-search (fetch PR context)
  |
  v
research-codebase (understand context)
  |
  v
plan-agent (plan for each comment)
  |
  v
[HUMAN CHECKPOINT: plan review]
  |
  v
[PREMORTEM: quick risk check]
  |
  v
kraken (implement_plan)
  |
  v
[HUMAN CHECKPOINT: verification]
  |
  v
commit (reference PR comments)

创建交接

始终创建交接，即使使用了 --dry-run：

---
session: fix-{scope}-{short-description}
ts: {ISO timestamp}
commit: {git commit hash}
branch: {git branch}
status: {complete|partial|blocked|diagnosis-only}
---

scope: {bug|hook|deps|pr-comments}
options: {flags used}

issue:
  description: {original user description}
  evidence: {key findings from investigation}

diagnosis:
  root_cause: {identified cause}
  hypothesis: {why we think this}
  files: [{affected files}]

fix:
  approach: {what was done}
  files_modified: [{files changed}]
  test_added: {test file if created}

verification:
  test_command: {command to verify}
  human_confirmed: {true|false}

next:
  - {any follow-up needed}

位置： thoughts/shared/handoffs/fix/{scope}/{timestamp}_{description}.yaml

示例

基本 Bug 修复

/fix bug
# -> Investigates, diagnoses, implements, tests, commits

仅诊断

/fix bug --dry-run
# -> Investigates, creates diagnosis handoff, stops

修复但不自动提交

/fix hook --no-commit
# -> Full fix workflow but stops before commit

快速修复（不创建回归测试）

/fix bug --no-test
# -> Implements fix, commits, no regression test

处理 PR 评论

/fix pr-comments
# -> Fetches PR, creates plan, implements, commits

错误处理

错误	操作
调查没有发现任何问题	请用户提供更多上下文
用户不认可诊断结果	根据用户输入完善假设
修复导致其他测试失败	回滚并完善方案
用户不认可验证结果	提议回退或调整
提交失败	呈现错误并询问是否重试

与其他技能集成

此技能负责协调：

• debug / debug-hooks：初步调查
• sleuth：并行调查 Agent
• kraken：TDD 实现 Agent
• implement_task：单任务实现
• test-driven-development：测试创建
• plan-agent：复杂修复规划
• dependency-preflight：依赖检查
• oracle / research-codebase：收集上下文
• github-search：获取 PR 上下文
• qlty-check：质量验证
• premortem：实施前风险评估
• commit：Git 提交工作流
• create_handoff：会话交接

检查点摘要

检查点	目的	跳过条件
诊断后	确认根本原因	从不跳过
事前分析后	接受或降低风险	没有 HIGH tigers
修复后	验证问题已解决	从不跳过
提交前	审查更改	--no-commit

人工检查点对于以下事项至关重要：

1. 防止实施错误的修复
2. 确保用户了解更改内容
3. 发现只有人类才能注意到的边缘情况