issue-spec

Issue specification

スコープ

このスキルが扱うのは仕様作成の方法であり、どの変更に仕様が必要かではありません。対象リポジトリの AGENTS.md と関連するリポジトリワークフローのオーバーレイを読み、常に仕様が必要な対象、ラベル、必須セクション、例外を確認してください。仕様を書くよう明示的に依頼されている場合は、そのまま着手できます。実行するかどうかを再確認する必要はありません。リポジトリで定められた仕様の形式を使用してください。GitHub issue ベースの SDD ループを採用している場合は GitHub issue を使用してください。推測で別のリポジトリの仕様形式に移行しないでください。

前提条件

変更の意図、対象リポジトリ、適用される契約を把握してください。GitHub での作業では、機能の対応付けが必要な場合に限り、harness-operations を使用してください。個人によるインストールや特定の GitHub ツールは必要ありません。仕様を作成する際は形式のリファレンスを読み、テンプレートは追加のポリシーではなく出発点として使用してください。

手順

1. 関連するコード、最近の変更、既存の issue／仕様を調べます。重複して作成するのではなく、関連する作業を再利用または修正してください。チェックアウト先／リモートと契約から対象リポジトリを特定し、このスキルのソースリポジトリから推測しないでください。
2. Overview、Design、個別に検証可能な Plan 項目、それに対応する Test 項目、Alignment、任意の Notes を使って意図を記述します。リポジトリで必須とされる影響／例のセクションも含めてください。仕様はおよそ 2000 トークン以下に収め、大きな機能は親項目と、それぞれ独立したスコープを持つ子項目に分割してください。
3. Alignment で境界を明示します。すでに承認されている実装上の判断に基づいて進めてください。作業に必要な具体的な未解決の人間による判断事項については、harness-operations によって対応付けられた構造化質問機能を使い、その判断事項の出所、影響を受ける Plan 項目、選択肢、トレードオフを明記してください。プレーンテキストの質問や「人間が決定する」というチェックリストだけでは、判断を求めたことにはなりません。依存する作業は明示的な回答を待ち、独立していて承認済みの作業は続けてください。同じ作業中に回答を仕様へ反映し、回答済みのブロッカーを解消してください。許可された質問ツールがない場合は、その制約を明記し、回答を推測せずに確立された引き継ぎチャネルを使用してください。
4. スコープ、不変条件、テスト範囲、依存関係、必須ラベルを検証します。GitHub の本文では、各説明段落またはリスト項目をソースの 1 行に収め、空行でブロックを区切ってください。作業の完了前に Plan 項目を完了済みにしないでください。
5. 利用可能な許可済みツールを使って仕様を公開または更新します。既存のリポジトリのラベル、優先度、領域に関する慣例を適用してください。この手順の例に分類体系があるからといって、新しい分類体系を作成しないでください。ネイティブのサブ issue がサポートされている場合はそれを使って子項目との関係を設定し、サポートされていない場合は明示的なリンクを記録してください。
6. 作業可能な状態になったら、pre-push と pr-lifecycle に引き継ぎます。リポジトリのワークツリー／ブランチ規則に従ってください。共通手順ではハーネスのブランチ接頭辞を指定しません。

完了

仕様のパス／URL、スコープ、判断事項、公開機能に関するブロッカーを報告してください。ローカルの下書きは、公開済みの issue ではありません。issue ベースの SDD では、最終的なデリバリーに Closes #N、部分的なデリバリーに Part of #N をリンクし、マージ後にのみ Plan の進捗を更新してください。リポジトリに仕様ゲートがない場合、仕様ゲートを導入しないでください。

任意のヘルパー

list helper と show helper は、認証済みの GitHub CLI と jq が必要な任意の CLI 便利機能です。これらの前提条件を満たせない場合は、代わりに接続済みの GitHub ツールを使用してください。