fix

Fix

バグの調査と解決を行うワークフローオーケストレーターです。問題の範囲に応じて、専門スキルを連鎖させます。

Usage

/fix <scope> [options] [description]

Question Flow (No Arguments)

ユーザーが引数なし、または一部の引数だけで /fix を入力した場合は、この質問フローに沿って案内してください。各フェーズでは AskUserQuestion を使用します。

Phase 0: Workflow Selection

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 の質問に進みます
• 「バグ」→ scope=bug に設定し、フェーズ 2（問題の詳細）に進みます
• 「フック」→ 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"

Phase 1: Issue Type

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 スコープ
• 「インポートエラー」→ deps スコープ
• 「PR のフィードバック」→ pr-comments スコープ

Phase 2: Issue Details

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

エラーメッセージ、予期しない動作、または PR のリンクを収集します。

Phase 3: Investigation Depth

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 エージェントに直接進みます

Phase 4: Testing & Commit

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

Summary Before Execution

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]

Scopes

スコープ	チェーン	説明
bug	debug -> implement_task -> test-driven-development -> commit	一般的なバグ修正ワークフロー
hook	debug-hooks -> hook-developer -> implement_task -> test hook	フックに特化したデバッグ
deps	dependency-preflight -> oracle -> plan-agent -> implement_plan -> qlty-check	依存関係の問題
pr-comments	github-search -> research-codebase -> plan-agent -> implement_plan -> commit	PR のフィードバックへの対応

Options

オプション	効果
--no-test	回帰テストの作成を省略します
--dry-run	診断のみ行い、修正を実装しません
--no-commit	修正を自動コミットしません

Workflow

Phase 1: Parse Arguments

# 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

Phase 2: Investigation (Parallel)

並行調査のために sleuth エージェントを起動します：

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.
  """
)

Phase 3: Diagnosis Report

調査結果をユーザーに提示します：

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

Phase 4: Human Checkpoint (Diagnosis)

必須： 実装を開始する前に、ユーザーの確認を待ちます。

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

ユーザーが「変更」と答えた場合は、新しい要件を収集して進め方を更新します。 ユーザーが「いいえ」と答えた場合は、診断内容を引き継ぎ用にまとめて終了します。 --dry-run の場合は、診断内容を引き継ぎ用にまとめて、ここで終了します。

Phase 4.5: Risk Assessment (Premortem)

診断の承認後、実装前に実施します：

提案された修正の簡易プレモーテムを行い、リスクを検出します：

/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 の tiger がない場合：実装に進みます
• HIGH の tiger が見つかった場合：次の選択肢をユーザーに提示します：
  • リスクを受け入れて進める
  • リスクに対処できるよう進め方を変更する
  • リスク軽減策を調査する

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 を並行して起動し、選択肢を再提示します。

Phase 5: Implementation

スコープに応じた適切な実装スキルに振り分けます：

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

Phase 6: Regression Test (unless --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
  """
)

Phase 7: Human Checkpoint (Verification)

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

「調整が必要」と言われた場合は、フィードバックを収集してフェーズ 5 に戻ります。 「元に戻す」と言われた場合は、ロールバックコマンドを実行して終了します。

Phase 8: Commit (unless --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
  """
)

Chain Details by Scope

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)

Handoff Creation

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

Examples

Basic Bug Fix

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

Diagnose Only

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

Fix Without Auto-Commit

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

Quick Fix (No Regression Test)

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

PR コメントへの対応

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

エラー処理

エラー	対応
調査しても何も見つからない	ユーザーに詳細情報を求めます
ユーザーが診断を受け入れない	ユーザーの入力をもとに仮説を練り直します
修正によって他のテストが失敗する	ロールバックし、アプローチを練り直します
ユーザーが検証を受け入れない	元に戻すか、調整するかを提案します
コミットに失敗する	エラーを提示し、再試行を提案します

他のスキルとの連携

このスキルは、以下をオーケストレーションします。

• debug / debug-hooks：初期調査
• sleuth：並行調査エージェント
• kraken：TDD 実装エージェント
• implement_task：単一タスクの実装
• test-driven-development：テストの作成
• plan-agent：複雑な修正の計画
• dependency-preflight：依存関係の確認
• oracle / research-codebase：コンテキストの収集
• github-search：PR コンテキストの取得
• qlty-check：品質の検証
• premortem：実装前のリスク評価
• commit：Git コミットのワークフロー
• create_handoff：セッションの引き継ぎ

チェックポイントの概要

チェックポイント	目的	スキップ条件
診断後	根本原因の確認	スキップ不可
premortem 後	リスクの受容または軽減	HIGH の tiger がない
修正後	解決の検証	スキップ不可
コミット前	変更のレビュー	--no-commit

人間によるチェックポイントは、以下の点で重要です。

1. 誤った修正が実装されるのを防ぐ
2. 何が変更されたかをユーザーが理解できるようにする
3. 人間にしか気づけないエッジケースを見つける