superpowers-issue-bridge

Superpowers Issue Bridge

この機能の位置づけ

Superpowers の brainstorming は会話です。まだインテント issue が存在しない作業では、2 通りの終わり方があり、ユーザーが選択します。

• Build now — brainstorming は通常どおり続行します。設計、次に計画、コード、そしてプルリクエストです。issue は関与しません。
• Track first — brainstorm-to-issue がインテント issue を起票し、セッションはそこで終了します。issue は後から、ユーザー自身、またはそれを基に作業するエージェントによって実装されます。

このブリッジは、その選択をめぐる瞬間を担います。選択肢を提示すること、すでに存在する issue から brainstorming を始めること、仕様と計画を issue まで遡って追跡すること、そして完成した作業を issue にリンクすることです。

ステップ 1 の前に — トラッカー設定を読む

docs/agents/issue-tracker.md を読みます。その Backend、Location、Reading、Linking の各セクションには、issue がどこにあるか、issue の読み方、そしてプルリクエストが issue をクローズまたは参照するために何を書き込むかが記載されています。

• GitHub で、Reading または Linking セクションがない場合（それらが存在する前に書かれた設定）: GitHub の慣例を使用します — #<number>、gh issue view、Closes #<number>、Relates to #<number>、gh issue close。
• それらがないその他のバックエンド: その issue の読み方とリンクの方法をユーザーに尋ねます。
• 設定ファイルがない場合: このチェックアウトの GitHub リポジトリを前提とせず、issue がどこにあるかを尋ねます。

以下の例では GitHub の構文を使用しています。トラッカー自身の構文に置き換えてください。

ステップ 1 — インテント issue を見つける

• ユーザーがそれを参照している（「#42 を実装して」、「PROJ-123 をビルドして」）。
• 現在のブランチ名に issue への参照が含まれている（例: feat/42-claims-status）。ユーザーに確認します — ブランチ名の数字が常に issue とは限りません。
• それ以外の場合は、存在するかどうかを尋ねます。言及されなかったからといって存在しないと決めつけず、参照を推測しないでください。

issue が存在する → ステップ 3。存在しない → ステップ 2。

ステップ 2 — まだ issue がない場合: build now か track first を提示する

brainstorming を通常どおりに始めさせます。プロジェクトを調査し、作業を分類し、問題についての明確化の質問をします。問題が理解されたら — brainstorming がアプローチを提案する前（アーキテクチャパス）または短い設計を提示する前（バウンデッドパス）に — それ自体の質問として尋ねます:

「これを今ビルドしますか、それともまずインテント issue としてトラッキングしますか？」

• Build now — brainstorming は変わらず続行します。issue がないため、ステップ 3〜5 は適用されません。
• Track first — これまでの会話に対して brainstorm-to-issue を呼び出します。ユーザーが明示的に下したすべての決定は、issue の Constraints セクションに入ります。issue が作成されたら、セッションは終了します。仕様も、writing-plans も、コードもありません。ユーザーの選択が、brainstorming の通常の次のステップに取って代わります。

答えがすでにわかっている場合は、質問をスキップします:

• ユーザーがすでにどちらかを言っている: 「just fix it」または「build it now」は build now を意味し、「file this」または「track it first」は track first を意味します。
• brainstorming がその作業をスパイクとして分類した。スパイクはトラッキングされる作業ではなく、答えで終わります。ユーザーは後からその発見を起票できます。

ステップ 3 — issue から brainstorming を始める

トラッカーの Reading メソッドで issue を読みます — GitHub では、gh issue view <number> --repo <owner/repo> --json title,body,url です。

その Problem / Proposed outcome / Affected users and systems / Constraints / Open questions を、すでに回答済みとして brainstorming に渡します:

• issue に記載されていることを再度尋ねないでください。
• Constraints は確定済みとして扱います。それらはユーザーがすでに下した決定を保持しています。ユーザーが再開する場合にのみ、再び取り上げます。
• issue がカバーしていないことを尋ねます。アーキテクチャパスでは、それは代替案、スコープ外の境界、エッジケースを意味します。バウンデッドパスでは、その短い設計が必要とする質問だけです。
• Open questions は、会話で解決されない限り、まだ回答が必要な質問として引き継ぎます。

ステップ 4 — 仕様と計画をイシューまで遡って紐づける

このステップは、ファイルを書き出す唯一の経路である brainstorming のアーキテクチャ経路に適用されます。仕様が書かれたら (デフォルトでは docs/superpowers/specs/ の下)、そのタイトルの直下に次の行を追加します。

Intent-Issue: #<number> — <url>

writing-plans が計画を書くとき (デフォルトでは docs/superpowers/plans/ の下)、同じ行をそのまま変更せずに、計画ヘッダーの **Spec:** 行の直後に引き継ぎます。ローカル Markdown の意図の場合、ファイルパスが #<number> — <url> を置き換えます。

スパイク経路と bounded 経路は仕様も計画も書き出しません。この行を保持するためにそれらを作成しないでください — ステップ 5 のリンクがトレースとなります。

ステップ 5 — 完了した作業をリンクで戻す

finishing-a-development-branch は作業が着地する場所です — subagent-driven-development と executing-plans はどちらもそこで終わります。ユーザーがそのオプションのいずれかを選んだら、一度だけ尋ねます: この作業は意図イシューを完全に解決しますか、それとも部分的ですか? その後、トラッカーの Linking セクションを適用します:

選んだオプション	完全に解決	部分的
プッシュして PR を作成	PR 本文に Finishing 参照 (Closes #<number>)。	PR 本文に Partial 参照 (Relates to #<number>)。
ローカルでマージ	参照を運ぶ PR がないため、自動で閉じるものはありません。ユーザーに伝え、マージがプッシュされたら手動でイシューを閉じることを提案します (gh issue close <number> --comment "Resolved in <sha>")。	マージがプッシュされたら、マージコミットを示すコメントをイシューに付けることを提案します (gh issue comment <number> --body "Progress in <sha>")。
そのまま保持	まだリンクするものはありません。	まだリンクするものはありません。

Linking セクションの Finishing PR が None の場合 — ローカル Markdown、またはどのインテグレーションも閉じない Jira や Trello ボード — は、PR は何も閉じません。どちらの場合も Partial 参照を書きます。イシューを完全に解決する作業については、PR がマージされてもイシューは閉じないことをユーザーに伝え、マージ後に実行するトラッカーの Close-by-hand ステップを提示します。

手動で閉じたりコメントしたりするとトラッカーが変更されます: ユーザーの承諾がある場合にのみ行ってください。

無人実行の場合 — 誰も尋ねる相手がいないままイシューを処理するディスパッチャ — は、代わりに実装者のレポートから判断します: イシューが求めている作業のうち、このリポジトリへの変更でまだ実行できるものは部分的を意味します。ここでの変更ではできないもの — オーナーによるプロビジョニングや本番実行、手動によるチェック、別のリポジトリでの作業、別のイシューが追跡する作業 — はフォローアップです: PR 本文に列挙し、それは作業を部分的にはしません。選択とその理由を PR 本文に記載し、実行終了時に部分的とした各項目についてユーザーに尋ねます。

デフォルトで閉じることにしないでください。意図イシューはしばしば 1 つの PR より大きく、早すぎる閉鎖はこのセットアップが守るために存在する監査証跡を壊します。

やってはいけないこと

• このブリッジのロジックを Superpowers 自身のスキルファイルにマージしないでください — 別のスキルとして保つことで、Superpowers の更新がそれを上書きしません。
• 意図イシューがすでに答えていることについてユーザーに再度ヒアリングしないでください。また、その Constraints を自分で再び開かないでください。
• ユーザーが先にトラッキングすることを選んだ後で、仕様を書いたり、writing-plans を実行したり、コードを書き始めたりしないでください。
• Intent-Issue: 行を保持するためだけに仕様や計画ファイルを作成しないでください。
• 「完全に解決」または「部分的」と決めつけないでください — PR またはマージごとに一度尋ねてください。
• イシュー参照をでっち上げないでください。見つけられない、または確認できない場合は、推測するのではなく、参照なしで進めてください。
• GitHub でないトラッカーに GitHub の #<number> や Closes 構文を使わないでください。
• ユーザーの承諾なしにイシューを閉じたりコメントしたりしないでください。