specify

Specify

エージェントツールキットのパイプラインで、specify フェーズを実行しています。Spine フェーズ 2 です。あなたの役割は、ローカルで可逆的な慣用的選択について実装の自由を保ちながら、plan および implement の前に、重要な動作上および契約上の判断をすべて確定することです。未解決の重要な判断があると、implement 中に差し戻しとなります。

manifest.class = epic の場合： このファイルの末尾にある Epic Specify の手順に従ってください。Epic specify の対象は横断的な契約に限られ、子項目ごとの実装の詳細は対象外です。

ヘルパースクリプトの実行

このスキルには、ヘルパースクリプトが独自の scripts/ ディレクトリに含まれています（この SKILL.md と一緒にインストールされています）。SKILL_DIR にこのスキルの絶対パスを設定します。パスはこのファイルの末尾に このスキルのベースディレクトリ として表示されています。その後、プロジェクトのルートディレクトリからスクリプトを実行してください（プロジェクトの .changes/ および CONTEXT.md ファイルを操作します）。

SKILL_DIR="<absolute path to this skill's directory>"

以下のすべての node "$SKILL_DIR/scripts/..." コマンドは、この設定を前提とします。packages/build/ は参照しないでください。このパスが存在するのはツールキットの開発リポジトリ内だけであり、インストール済みスキルにはありません。

あなたの姿勢

architect と同じ対立的な姿勢を取ってください。references/challenge-protocol.md、references/adversarial-review.md、references/engineering-fundamentals.md を再読してください。ユーザーが決めるべき重要な判断ごとに、最善の解決策を提案してください。ユーザーに尋ねるのは、公開契約、セキュリティポリシー、互換性／移行、明確な境界、元に戻せない、またはコストのかかる決定、そして重要なアーキテクチャ上または運用上のトレードオフに限ります。ローカル／プライベート／可逆的な詳細については、一般的で慣用的な選択を自動で採用してください。本当にユーザーの判断が必要な事項について、返答がないことを承認と見なしてはいけません。

前提条件

manifest.yaml を読み込み、次の点を確認してください。

• phase が specify である（つまり、architect の承認が承認済みである）。
• approvals.specify が pending である。
• architecture.md が存在し、妥当性チェックに合格している。
• class = epic の場合： 以下の Epic Specify セクションに移動してください。

前提条件を満たさない場合は、何が問題なのか、代わりにどの手順を実行すべきかをユーザーに伝えてください。

architecture.md 全体を読み込んでください。これが仕様の基準となります。

manifest.language が設定されている場合は、インターフェース設計の指針として、idioms スキルを使って該当する言語パックを読み込んでください。一致するパックがインストールされていない場合は、その旨を明示し、パックの指針を推測するのではなく、リポジトリの規約とツールを使用してください。

フェーズ 1：インターフェースの一覧化

インタビューの前に、architecture.md から次の項目を抽出してください。

• 新規または変更されるすべての境界
• 判断事項で言及されているすべてのインターフェース
• 対象範囲内のすべてのリファクタリング

それらをレビュー対象として列挙してください。重要性の境界を越える選択についてのみ質問してください。設定や可観測性の詳細について、ユーザーの判断が必要となるのは、それが公開／運用上の契約、セキュリティポリシー、コストのかかる決定、または重要なトレードオフを定める場合に限ります。ローカル／プライベート／可逆的な詳細には、リポジトリの規約と慣用的な方法を使用してください。

フェーズ 2：バッチ形式での意思決定の確認

簡潔な番号付きバッチで、体系的な確認インタビューを実施します。ルール：

• 各項目には、ユーザーが決定する重要な質問、エージェントの推奨、推奨の根拠、および有意義な代替案を記載します。
• すべての項目について、明示的な回答を必須とします。回答は accept、代替案の選択、または決定の提示のいずれかです。ユーザーは項目番号だけで簡潔に回答できます。
• 回答がない、曖昧、または不明確な項目は unresolved のままにします。未解決の項目についてのみ追加確認し、沈黙を承認と推測してはいけません。
• 回答に異議を唱えるのは、その回答が曖昧な場合、問題のある兆候を持ち込む場合、またはイディオムパックと矛盾する場合に限ります。ユーザーが異議を覆した場合は、推奨、ユーザーの決定、および提示されている場合はその理由を記録します。
• ユーザーが決定する重要な項目がすべて明示的に確認されたら終了します。リポジトリの規約とイディオムに従うローカル／プライベート／可逆的な詳細について、質問や台帳の項目を作成してはいけません。

以下のカテゴリを検討します。ただし、選択が重要性の境界を越える場合にのみ質問します。

1. インターフェース定義 — 正確なシグネチャ、型、エラー条件、エッジケース
2. データ契約 — フィールド名、型、必須か任意か、検証ルール
3. エラー処理 — architecture.md に記載されている各失敗モードと、その場合の処理
4. 並行処理／順序 — 変更が並行コードに関わる場合の順序保証
5. 設定 — 新しい設定項目、そのデフォルト値、検証方法
6. 移行／互換性 — 破壊的変更かどうか、後方互換性の要件
7. テストシナリオ — 確定した各接点で網羅すべきシナリオ
8. 可観測性の詳細 — 正確なメトリクス名、トレーススパン、ログレベル
9. リファクタリングの範囲 — 承認された各リファクタリングの対象ファイル／モジュールと変更内容

作業中は確認台帳を維持します。解決済みの各項目には、決定 ID、推奨、ユーザーの明示的な回答、および confirmed ステータスが必要です。この台帳は decisions.md に使用します。

フェーズ 3：範囲を限定した「実装するなら」のレビュー

確認後、references/adversarial-review.md に従って SV-* サイクルをちょうど 1 回実行します。新たな実装者兼批評者が、architecture.md、決定事項の草案、および関連するリポジトリのコンテキストを対象に、広範な読み取り専用の「実装するなら」レビューを 1 回実施します。該当する範囲で、データ／状態、データ構造、インターフェース／トレイト、エラー、セキュリティ、可観測性、単純さ、保守性、イディオムを深く検討します。実装の自由度が残っているというだけの理由で、プライベートな制御フローを指示してはいけません。

すべての指摘を 1 つのバッチにまとめます。各指摘には、安定した SV-NNN ID、重大度 blocker|major、カテゴリ correctness|security|simplicity|maintainability|idioms、根拠、具体的な影響、および具体的な代替案を含めます。軽微な指摘や、必須の N/A 行は出力しません。

バッチ全体を 1 回で修正します。修正が重要性の境界を越える場合にのみ、ユーザーの確認を得ます。ローカル／プライベート／可逆的で、慣例に沿ったイディオム上の選択は自動的に採用します。その後、新たな検証者を起動し、元の ID のみを確認します。検証では発見を繰り返したり、範囲を拡大したり、新たな軽微または重大な指摘を追加したりしません。修正に起因する blocker の再発のみが新しい ID の例外です。これを --regression とともに記録し、同じ限定的な範囲内で修正し、1 回の対象限定再検証において --regression-resolution で解決します。未解決の ID が残る場合、または解決に広範な調査が必要な場合は、サイクルを延長せずに停止します。

review-log.mjs を使用し、現在のマニフェストの specify-N エポックに発見と検証を記録します。監査者は共有ポリシーに基づく構造化された --finding JSON を使用し、検証者は元の各指摘について --resolution SV-NNN=resolved|unresolved を 1 つずつ指定します。監査者が問題なしと承認した場合も、別途検証者が必要です。

node "$SKILL_DIR/scripts/review-log.mjs" record --id <id> --phase specify --cycle specify-N \
  --role auditor --reviewer "<fresh label>" --verdict approved
node "$SKILL_DIR/scripts/review-log.mjs" record --id <id> --phase specify --cycle specify-N \
  --role verifier --reviewer "<distinct fresh label>" --verdict approved

フェーズ 4：decisions.md を作成する

references/templates/decisions.md.tmpl をもとに decisions.md を作成します。以下を含めてください。

• 散文形式の決定事項より前に、確認事項の一覧をすべて記載します
• すべてのインターフェース変更を記載します（完全かつ正確に）
• 決定ログ全体を記載します（バッチ項目 → 推奨事項 → 明示的な解決、異議、上書き）
• 範囲を限定した SV-* レビューサイクルと、焦点を絞った検証結果
• アーキテクチャの整合に関する注記（architecture.md に見つかった相違点と、その修正方法）

保存先：.changes/active/<id>/decisions.md

インタビュー中に新しい CONTEXT.md の対象が特定された場合は、manifest.yaml context_targets を更新します。

フェーズ 5：architecture.md を整合させる

decisions.md と architecture.md を比較します。アーキテクチャ上の決定を変更、明確化、または矛盾する決定がある場合：

• architecture.md を更新し、明確になった内容を反映します。
• 「Architecture Reconciliation」の下に、整合内容を decisions.md に記録します。

フェーズ 6：承認

確認事項の一覧、確定したインターフェース、ドライランの結果を提示します。この一覧がユーザーの選択を正確に表しているか、ユーザーに確認します。その後、次のように尋ねます。

"ユーザーが決定するすべての重要事項が明示的に確認され、範囲を限定した仕様レビューに未解決の阻害要因はありません。specify の承認を行いますか？（これにより plan に進みます。）"

承認された場合：

node "$SKILL_DIR/scripts/manifest-approval.mjs" --id <id> --approval specify --approve

ユーザーに、次に plan を実行してください。 と伝えます。

implement から差し戻された場合の対応

新しいセッションではなく、implement からの差し戻しで specify を実行している場合は、修正セッションとして扱います。

• manifest.yaml から差し戻し項目を読み込みます。
• 差し戻しで特定されたギャップのみを解消します。
• 現在の specify-N の正式なサイクルを、記録されたギャップだけを対象として実行します。広範な調査を再開してはいけません。新たな重要な決定事項が見つかった場合は、その決定を確認し、サイクルの範囲を広げずに差し戻し項目の下に記録します。
• 新たな解決内容で decisions.md を更新します。
• 必要に応じて architecture.md を整合させます。
• manifest.yaml の最新の差し戻し項目にある resolution を、実際の決定内容に設定します。空欄のままにしたり、pending のようなプレースホルダーを使ったりしてはいけません。
• 無効になった承認のみを再承認します。specify に影響する差し戻しの場合は specify の後に plan が必要です。plan のみの差し戻しの場合は plan のみが必要です。
• 実装を再開するようユーザーに伝える前に、manifest が推奨する次のフェーズを確認します。

参照ファイル

• references/challenge-protocol.md
• references/adversarial-review.md — 範囲を限定した SV-* レビューサイクルと指摘事項のスキーマ
• references/seam-and-test-taxonomy.md
• references/manifest-schema.md — 差し戻しの種類とエピックのモデル
• references/firm-change-protocol.md — 確定したインターフェースを変更する必要がある場合
• references/templates/decisions.md.tmpl
• idioms スキル — インターフェース設計に関する指針

---

EPIC SPECIFY PATH — class: epic

エピックの specify は、複数の子が合意する必要のある、横断的な契約のみを対象とします。子ごとの実装詳細に踏み込んではいけません。それぞれの子自身の specify セッションで扱います。

「横断的」の意味

横断的な懸念事項とは、2 つ以上の子の変更がともに影響を受ける、または依存するものです。例：

• 子 A が生成し、子 B が消費する、共有メッセージ形式またはワイヤープロトコル
• 複数の子が参照する共有データ構造（ドメイン型、エラー列挙型など）
• すべての子が読み取る設定スキーマ
• コンポーネント間のイベントまたは通知の契約
• すべての子で一貫させる必要があるエラー処理の規約

契約またはインターフェースがちょうど 1 つの子にのみ属する場合、それは横断的ではありません。ここでは扱わず、その子の specify で処理します。

Epic の Specify フェーズ

フェーズ E1：横断的な項目の特定

architecture.md から、以下を抽出します。

• 「Proposed Child Changes」セクションで、子間で共有されると示されているすべてのインターフェース
• 複数の子がまたぐすべての境界
• 明示的な「cross-cutting concerns to resolve in specify」セクション

これらを一覧にします。このセッションで扱うのはこれらのみです。

フェーズ E2：まとめて決定（横断的な項目のみ）

標準的な重要度の基準と確認手順を厳密に適用します。共有するパブリック契約、セキュリティポリシー、互換性／移行、明確な境界、コストの高い決定、または子間で意味のあるアーキテクチャ上／運用上のトレードオフについてのみ質問します。ローカル／プライベート／変更可能な一般的な選択は自動的に決定します。以下を確認します。

• 各共有インターフェースの正確な型シグネチャ、メッセージ形式、エラー型
• 各共有契約を所有（作成）する子と、それを利用する子
• バージョン管理／進化のルール：他の子を壊さずに、Epic の途中で共有インターフェースを変更できるか
• 順序の制約：子 A が提供するインターフェースを子 B が利用する場合、子 B が specify を開始する前に、子 A のインターフェースを完成させる必要があるか

フェーズ E3：範囲を限定した子間レビュー

すべての子間契約に対して、SV-* サイクルをちょうど 1 回実施します。新しい批評者 1 名が、すべての子間の境界と該当するすべてのレビュー観点を対象に、実装する立場で広範な確認を 1 回行います。安定した SV-NNN ID、必須カテゴリ、根拠、具体的な影響、代替案を含む、統合したブロッカー／重大事項の一覧を提示します。重要な決定についてのみユーザーに確認しながら、1 回だけ修正します。新しい検証者が元の ID のみを確認します。的を絞った修正／再検証は最大 1 回までとし、発見の繰り返しや、新たな重大／軽微な指摘は行いません。このサイクルを Dry-Run Findings に記録します。元のブロッカーが残っている場合、Epic を分割してはいけません。

標準の手順と同様に、現在の specify-N エポックの下で review-log.mjs を使って監査者と検証者を記録します。

フェーズ E4：Epic の decisions.md を作成

以下を網羅する decisions.md を作成します。

• すべての横断的なインターフェース定義（完全かつ正確なもの）
• 所有権マップ：各共有インターフェースを作成する子
• 子間の順序の制約
• ドライランの指摘事項と解決策
• この文書で明示的に対象外とする内容（子ごとの specify に委ねる内容）

保存先：.changes/active/<id>/decisions.md

フェーズ E5：承認＋自動分割（ユーザーではなく、あなたが実行）

まず、specify の承認を行います。

node "$SKILL_DIR/scripts/manifest-approval.mjs" --id <id> --approval specify --approve

続けて、直ちに epic-split を自動実行します — ユーザーに手動で行うよう求めてはいけません。architecture.md の「Proposed Child Changes」セクションと、decisions.md の順序／所有権に関する決定を読み取り、children JSON を構築して、以下を実行します。

node "$SKILL_DIR/scripts/epic-split.mjs" --epic <id> --children '[
  {
    "title": "Child 1 title",
    "class": "feature",
    "language": "rust",
    "notes": "Brief scope: what this child owns, what interfaces it produces, what it depends on from sibling children. 2-3 sentences."
  },
  {
    "title": "Child 2 title",
    "class": "feature",
    "language": "rust",
    "notes": "..."
  }
]'

各子には、そのメモと、親コンテキストとして Epic の arch+decisions を暗黙的に参照できる architect-seed.md が用意されます。

epic-split の完了後、ユーザーに次のように伝えます。

「Epic を分割しました。[N] 件の子変更を作成しました。各子の architect セッションは、この Epic のアーキテクチャと決定事項を親コンテキストとして引き継ぎます。

深さ優先で作業してください。次の子に着手する前に、1 つの子を archive-ready まで完了させてください（architect → specify → plan → implement → archive-ready）。 完了した子を個別にアーカイブしてはいけません。Epic は archive-ready のすべての子を保持し、すべての子の準備が整った後、検証済みの一括処理でアーカイブします。

推奨順序（依存関係に基づく）：

1. [child-id-1] — [タイトル]（依存関係なし。ここから開始）
2. [child-id-2] — [タイトル]（子 1 の X インターフェースに依存） ...

独立した子は並行して進めてもかまいませんが、それぞれ全工程を最初から最後まで完了してください。準備ができたら、最初の子に対して architect を実行してください。「what now」と聞けば、いつでも進捗を確認できます。」