refine

name	refine
description	解決したい課題を refine し、論点ごとに選択肢と推奨案を検討して実装方針を導く

Refine

解決したい課題を受け取り、それをどう実装すべきかを導く。

このスキルは 入出力を扱う方法を定義しない。課題がどこから来て (GitHub Issue / チャット / その他)、結果をどこへ返すかには関知しない。それらは呼び出し側 (Issue ラッパー、あるいはチャットの会話そのもの) の責務。このスキル自身は「課題 → 実装方針」の、状態を持たない 1 パスの変換に徹する。状態遷移・往復の管理・トランスポート固有の装飾はすべて呼び出し側が持つ。

入力

• 引数 (args) があればそれを課題の記述とする。
• 呼び出し元 (ラッパー等) が課題本文 + これまでの議論 (ユーザーの回答を含む) を渡す場合は、それらすべてを文脈として扱う。
• 課題が不明瞭で何も判断できないときだけ、その旨を 1 行返して停止する (推測で実装方針を捏造しない)。

処理

1. 課題と (あれば) これまでの議論から、次を整理する:

   • 現時点で 合意できている / 自明な前提 (確定事項)
   • 実装方針を確定させるために決める必要がある 論点 (= 決めるべき選択ポイント)。Yes/No か、択一で答えられる粒度に分解する。

2. 論点を埋める前に、必要な調査を行う。 実装前提となる調査はここで済ませる。調べれば分かることはユーザーへの質問にせず、調査で判明した事実を論点・推奨案の根拠にする。「何を refine するか」「結果をどこへ返すか」は呼び出し側が決めるが、refine に必要な情報の収集はこのスキルが共通して担う。

   • ソースコード: 関連する実装・既存の挙動・制約を Grep / Read で確認する。
   • 関連 Issue / PR: gh search issues / gh search prs (または GitHub MCP) で本課題に関連しそうな Issue / PR を探し、その議論・決定・実装内容を踏まえて論点と推奨案を組み立てる。
   • 外部情報: 仕様・ライブラリの挙動・一般的な設計判断など外部情報が必要なら WebSearch / WebFetch で調べる。
   • 調査を含め、refine 中はソースコードを変更しない (読み取り専用)。コードの変更は実装フェーズ (このスキルの外) で行う。

3. 各論点について、Claude 自身が答えを検討して埋める。 ユーザーに丸投げの質問を並べるのではなく、論点ごとに次をすべて行う:

   • 取りうる 選択肢 を列挙する (最低 2 つ。Yes/No 型なら「やる / やらない」)。
   • 各選択肢の 利点・欠点 を明確に書く。
   • 文脈・一般的な設計判断を踏まえて 推奨案 を 1 つ選び、なぜそれが良いかを因果で 書く。
   • 客観的な優劣がなく Claude が決められない (= 純粋にユーザーの好みに依存する) 論点に限り、推奨を「保留」とし、その旨と判断材料を書く。安易に保留へ逃げず、可能な限り埋める こと。
   • 「保留」とした論点 = 回答必須の論点 (Claude が客観的に決められず、ユーザーの回答がなければ実装方針を確定できない論点)。

4. 出力を組み立てる前に、サブエージェント (Agent ツール, subagent_type=general-purpose) を起動して論点と回答をレビューする。

   • サブエージェントには課題・これまでの議論・整理した論点と推奨案を渡し、次の観点で問題点を箇条書きで返させる (ファイルは変更させず、指摘のみ返させる):
     • 各論点の 推奨案 (回答) が妥当か — 選択肢の利点・欠点の評価が正しいか、推奨理由に飛躍・事実誤認・見落としが無いか。
     • 洗い出せていない論点が無いか — 仕様確定に必要なのに挙げ忘れている決定ポイント、考慮漏れの選択肢が無いか。
   • 返ってきた指摘は Claude が妥当性を判断し、妥当なものだけ反映する。妥当な指摘で論点・選択肢・推奨案の追加や変更が必要なら修正し、修正後はもう一度サブエージェントでレビューする。妥当な指摘が無くなるまで繰り返す。
   • 繰り返しは 最大 3 回 まで。3 回でも妥当な指摘が残る場合は、残った論点を「未解決の論点」として出力に明記したうえで打ち切る (再試行を無限に続けない)。
   • レビューを経て推奨案が当初案から変わった場合は、なぜその選択肢に至ったか を出力の推奨理由に織り込む。

出力

以下の構造で組み立てる。冒頭・末尾に「お疲れさまです」等の前置きは入れない。トランスポート固有の装飾 (マーカー・バッジ、合意を促す呼びかけ等) は付けない — それは呼び出し側の責務。確定事項・論点のセクションは、書くことが無ければ省略してよい。

出力の見出しはすべて h1 (#) にする。 確定事項と各論点は並列の関係にあり階層構造を持たないため、入れ子にせずフラットに並べる。実装方針の出力も同様に h1 で揃える。

# 確定事項
- ...

# 論点 1: <論点を一言で>
<1〜2 文で何を決めるのかを説明>

| 選択肢 | 利点 | 欠点 |
|---|---|---|
| **A: ...** | ... | ... |
| **B: ...** | ... | ... |

**推奨: A** — <推奨理由を因果で 1〜3 文>

# 論点 2 🔴 要回答: <論点を一言で>
<推奨が「保留」になる (= 回答必須の) 論点は、見出しに `🔴 要回答` バッジを付ける>

| 選択肢 | 利点 | 欠点 |
|---|---|---|
| **A: ...** | ... | ... |
| **B: ...** | ... | ... |

**推奨: 保留** — <Claude が客観的に決められない理由と、ユーザーが選ぶための判断材料>

---
**回答必須の論点: あり (論点 2)**

回答必須の論点の明示 (呼び出し側やユーザーが、このまま実装方針へ進めてよいかをひと目で判断できるようにするため):

• 回答必須 (= 推奨が「保留」) の論点は、見出しに 🔴 要回答 バッジを付ける。
• 出力の 末尾 に、回答必須論点の有無を 1 行で示すサマリーを置く:
  • 必須ゼロのとき: **回答必須の論点: なし**
  • 必須ありのとき: **回答必須の論点: あり (論点 N)** (複数あれば (論点 N, M) のように列挙)

実装方針

回答必須の論点が 1 つも無い とき (= Claude が全論点を決められる、または呼び出し元がユーザーの回答を渡しており未確定が解消されている) は、上記に続けて実装方針を出力する。各論点は、ユーザーが別の選択肢を指定したものはその選択を、特に異論が無かったものは推奨案を、確定した答えとして反映する。元の課題や議論にあった情報を取捨選択し、実装可能な粒度に整える。

# 背景 / 目的
なぜこれをやるか (1〜3 段落)

# 仕様
何をするか。UI 変更があれば挙動を、API 追加があればシグネチャを書く

# 非対象 (やらないこと)
- ...

# 完了の定義
- [ ] ...
- [ ] ...

回答必須の論点が残るときは実装方針を出さない (論点への回答が先)。回答を集める方法・いつ実装方針へ進むかの判断は、呼び出し側が持つ。

ガード

• refine 中はソースコードを変更しない (読み取り専用)。コードの変更は実装フェーズ (このスキルの外) で行う。
• 推測で論点や事実を捏造しない。調べれば分かることは調査し、決められないものは「要回答」として残す。