linear-refine

Linear Refine

ワークフローのソースとしてリポジトリのルートを使用します。以下を読み、従ってください。

• agents/questioner.md
• docs/questioner.md
• docs/agent-required-passes.md
• docs/superpowers-linear-persistence.md
• templates/linear-plan-comment.md
• schemas/linear-ai.plan.v1.schema.yaml

質問は一度に1つずつ行います。プランを準備完了とする前に、必須のローカルレビュー／グリルパスを実行します。

Claim Lock

docs/workflow.md の Claim Lock Rule に従ってください。開始時に、イシューを再度読み込みます。すでに in-use が付いており、この実行が自身の claim の再開ではない場合は、変更を加えず、イシューが claim 済みであることを報告して停止します。それ以外の場合は、イシューを claim する際に in-use ラベルを追加します。この実行がイシューの作業を停止した時点で、in-use を削除します。対象は準備完了の引き継ぎ、ブロック、または放棄です。in-use は llm-* 名前空間の対象外であるため、明示的に解除してください。

claim 時には、claimed_by: linear-refine と ISO 8601 形式の claimed_at を含む linear-ai:claim ブロック（templates/linear-claim-block.md）もイシューの説明に書き込み、ほかの説明内容は保持してください。解除時には claim ブロックを削除します。

Questionnaire Start

準備完了のプランを書く前に、ソースの証拠に基づいて、質問票が必要かどうかを判断します。ソースの証拠には、イシュー、コメント、リンクされたドキュメント、コードベースの調査が含まれます。重要な曖昧さが残っていない場合は、質問票が不要だったことを記録して、準備完了のプラン作成に進みます。

重要な曖昧さとは、合理的な選択肢によってプロダクトの動作、UX、スコープ、またはデータの意味が変わり得る分岐のことです。設計上の選択肢に妥当な候補が複数ある場合は、コード上の証拠が一方を支持していても、常に重要な曖昧さとして扱います。証拠を推奨回答とともに提示し、独断で決定しないでください。質問せずに決定できるのは、純粋に機械的な選択（命名、ファイルの配置、既存の完全に同一なパターンの再現）のみです。却下した選択肢は do_not_assume に記録してください。

ソースの証拠を調べ尽くしても重要な曖昧さが残る場合は、コピーしたグリル文面に頼らず、実際の質問票／インタビューの手順を開始してください。利用可能な場合は grill-me または grill-with-docs を使用しますが、これらのスキルがインストールされていることを必須条件にしないでください。利用できない場合は、フォールバックを直接実行します。具体的な質問を1つだけ行い、推奨回答を添えて、ユーザーの返答を待ってから次の質問を行います。

質問票の証拠により、すべての重要な曖昧さについて回答済み、または不明のままであることが明示的に承認されるまでは、plan_status: ready にしないでください。

Subagent Relay Mode

直接やり取りする人間の窓口がないバッチサブエージェントとして実行する場合でも、インタビューの要件は免除されません。各質問ラウンドをディスパッチ元のオーケストレーターに送り、回答が中継されるのを待ちます。待機中も in-use の claim を維持してください。重要な質問が未回答で、オペレーターによる不明のままでよいという明示的な承認もない間は、決して plan_status: ready にしないでください。

Non-Technical Intake Handoff

イシューに nontechnical-intake が付いている場合は、技術的な翻訳が必要な平易な言葉によるインテークとして扱ってください。

準備完了のプランを書く前に、以下を行います。

• 元の平易な言葉による報告を保持します。
• Technical triage gaps セクションを読みます。
• イシュー、コメント、リンクされたドキュメント、Linear のコンテキスト、リポジトリの証拠から、影響を受けるシステムを特定します。
• 望ましい成功を、テスト可能な受け入れ基準に変換します。
• Technical triage gaps を技術的な調査結果で置き換えるか、補完します。
• 利用可能な証拠から解決できない不明点は、明示したままにします。
• 残る不明点が解決されるか、明示的に承認されるまでは、plan_status: ready にしないでください。

技術的なトリアージが完了したら、通常のリファイン用ラベルの移行を適用しながら save_issue で nontechnical-intake を削除します。Linear への書き込みが利用できない場合は、REQUIRED_LINEAR_MUTATIONS に nontechnical-intake の削除を含めます。

グリルの継続

計画における重要な分岐のすべてについて、共通理解が得られるまで人間に徹底的に質問します。設計ツリーを一度に1つずつ進め、決定間の依存関係を解決し、それぞれの質問に推奨する回答を示します。

質問は一度に1つだけにします。課題、コメント、リンクされたドキュメント、またはコードベースを調べれば回答できる質問については、質問するのではなく、それらの情報源を調べます。

人間の回答ごとに、確定した決定を言い換えて確認し、可能であれば計画の草案または Linear のコメントを更新し、その分岐についてほかに追加することがあるか尋ねます。ある場合は、次の焦点を絞った質問をして現在のステップを続けます。ない場合は、分岐が解決済みであることを確認してから、次の分岐に進むか、次のワークフローステップへの移行を推奨します。

すべての重要な分岐についてグリルの継続が完了するか、人間が残っている不明点を明示的に受け入れるまで、plan_status: ready にしないでください。

Linear MCP の契約

利用可能な場合は、次の Linear MCP ツールを使用します。

• get_issue - 現在の課題のフィールド、ラベル、ステータス、ブランチのメタデータを読み取ります。
• list_comments - 新しいリビジョンを作成する前に、既存のマーク付き計画／ステータスコメントを読み取ります。
• save_comment - マーク付き計画コメントを投稿するか、該当するスレッドに返信します。
• save_issue - llm-ready を適用し、ほかの llm-* ラベルを削除し、開始時に in-use の申請ラベルを追加し、停止時に削除して、書き込みが可能な場合はステータスを更新します。

マーク付き計画コメントを次の内容で検証します。

scripts/validate_marked_comments.ts <plan-comment-file>

Linear のメタデータスナップショットが利用可能な場合は、次の内容でラベルを検証します。

scripts/validate_marked_comments.ts --metadata <metadata.json> <plan-comment-file>

エージェントが利用可能なローカルの JavaScript パッケージマネージャーまたはランタイムを使用します。Bun では .ts スクリプトを直接実行できます。Node/npm/pnpm/yarn 環境では、tsx などの TypeScript ランナーを介して実行します。

Linear MCP の書き込みツールが利用できない場合、ラベル、ステータス、コメントを更新したと主張してはいけません。正確なコメント本文とラベル／ステータスの変更を含む REQUIRED_LINEAR_MUTATIONS を出力します。

ステップ完了時の引き継ぎ

リファインによって草案、ブロック中、または準備完了の計画リビジョンが完成したら、変更点、検証／書き込みの根拠、現在の Linear のラベル／ステータス、推奨する次のステップを報告します。

このリファインステップに追加することがあるか尋ねます。ある場合は、現在のステップを続けて計画を更新します。ない場合は、次のワークフローステップへの移行を推奨します。通常、llm-ready がある場合は linear-implement、不明点が残っている場合は別のグリル分岐を推奨します。

追加することへの回答が「いいえ」の場合、推奨する次のスキルに進みたいか尋ねます。推奨する次のスキル名を明示し、ユーザーの確認を待ちます。自動で実行してはいけません。

次の形式で回答します。

• 現在のフェーズ
• 変更点
• 根拠
• 根拠不足の項目
• 未解決のブロッカー
• 推奨する次のステップ
• 推奨する次のスキル
• 質問：次に進む前に追加することはありますか？
• 質問：推奨する次のスキルに進みますか？

最新のマーク付き計画コメントが plan_status: ready で、ラベル／ステータスの変更が適用または出力され、受け入れられていないブロッキング質問が残っていない場合に停止します。