to-issues

to-issues — PRD/SPEC から Issue へ

PRD や技術 SPEC を、小さく、それぞれ単独でデモ可能な Issue に分解します。各 Issue は、新たに開始した 1 つのコンテキストウィンドウに収まるサイズにし、選択したプラットフォームで作成します。単独で動作するため、事前に /prd を実行しておく必要はありません。

このスキルが作成するすべての Issue は、作成時点でエージェントがすぐに着手できる状態です。PRD や SPEC を見たことがない新しいセッションでも、Issue を引き受けて完了できます。

---

基本原則：レイヤーではなく、トレーサーバレット

これは最も重要なルールであり、モデルが最も頻繁に破るルールです。

• 水平スライスでは、変更の 1 つのレイヤーだけを出荷します（すべてのスキーマを 1 つのチケットに、すべての API を別のチケットに、すべての UI をさらに別のチケットにまとめます）。すべてのレイヤーが揃うまで何も動作せず、各チケットの受け入れ条件が、別のチケットの担当範囲に踏み込む必要があります。モデルが陥りやすいのはこの形です。避けてください。
• 垂直スライス、つまり トレーサーバレット では、すべてのレイヤーを通る薄くても完全なパスを一度に出荷します（1 つの狭い動作に対するスキーマ + API + UI + テスト）。反映された時点ですぐに単独で検証でき、その評価に必要なすべてを担当します。

すべての Issue に対するテスト：「これが完了したら、何をデモできますか？」 答えが「ユーザーがタスクの優先度を設定し、その値が保持されるのを確認できる」ではなく、「データベースに優先度カラムがある」のようにレイヤーを指しているなら、それは水平スライスです。分割し直してください。

**サイズの下限：**変更全体が 1 つのコンテキストウィンドウに収まるなら、そもそも Issue は不要です。その旨を伝え、ユーザーに /goal を直接案内してください。

このスキルは /prd-to-spec と同じコンテキストウィンドウで使ってください。その間にコンテキストをクリアしたり圧縮したりしないでください。そうすると SPEC を再取得する必要が生じ、途中で切り詰められる可能性があります。

---

作業内容

1. 入力を特定する — PRD または SPEC ファイルを探します（自動検出またはユーザー指定）
2. 事前リファクタリングを探す — 「変更を容易にしてから、容易な変更を行う」ための作業を見つけ、最初に並べます
3. 垂直 Issue に分解する — 動作をトレーサーバレットチケットに分け、ブロッキング関係を設定します
4. ユーザーに確認する — 番号付きリストを提示し、公開前に粒度、依存関係、デモパスについて検討します
5. プラットフォームを選ぶ — GitHub / Local
6. Issue を作成する — ブロッカーを先に作成し、ネイティブのブロッキングリンクを設定してから、概要を出力します

---

ステップ 1：入力を特定する

入力ドキュメントを探します。

What should I base the Issues on?

A. Auto-detect: scan tasks/ for recent PRDs and SPECs
B. Specific PRD file (e.g., tasks/prd-priority-system.md)
C. Specific SPEC file (e.g., tasks/spec-priority-system.md)
D. Both PRD and SPEC (best: PRD for requirements, SPEC for technical contracts)
E. Paste requirements directly

自動検出する場合は、利用可能なファイルの一覧を表示し、ユーザーに選択してもらいます。

PRD と SPEC の両方がある場合は、SPEC のセクション 10.2（Issue マッピング）を主な指針として使用し、PRD のユーザーストーリーで補足します。PRD しかない場合は、ユーザーストーリーから直接 Issue を生成します。

---

ステップ 2：まず事前リファクタリングを探す

機能を分割する前に、事前リファクタリングを探します。機能 Issue を小さく安全にするための機械的な下準備です。共有ヘルパーの切り出し、型の拡張、シームの追加、ファイルの移動などが該当します。この作業を最初に独立した Issue として並べ、それに依存する機能チケットの範囲を小さく保ちます。

見つからなければ、このステップは省略します。無駄な作業を作り出さないでください。

---

ステップ 3：垂直型 Issue に分解する

Issue の一覧を作成します。ルール：

• 各 Issue はトレーサーバレットです — 対象となるすべてのレイヤーを通る、範囲が狭く、完結していて、デモ可能な経路にします。「X のバックエンド」ではなく、「あるケースにおける X のエンドツーエンド」とします。
• 各 Issue は新しいコンテキストウィンドウ 1 つに収まります — 1 回のエージェントセッションで、あなたが同席しなくても完了できる内容にします。
• レイヤーではなく振る舞いで分割します — ユーザーストーリーの規模が大きい場合は、引き続き垂直型となる、より範囲の狭い振る舞いに 2～3 個に分割し、ブロック関係を明示します。バックエンドのチケットとフロントエンドのチケットに分割してはいけません。
• 小さなストーリーは統合します — 単独ではデモにならない 1～2 個の簡単な基準は、関連する Issue に統合します。
• ブロック関係を明示します — 各 Issue に、着手前に完了している必要があるものを記載します。これらの関係こそが、この成果物の要点です。
• 依存関係の順に Issue に番号を付けます — ブロッカーを先にすることで、実装担当者（またはトラッカー）が常に着手可能な項目を把握できます。
• SPEC が利用可能な場合 — SPEC の参照（API コントラクト、データモデルのセクション、エラー処理）で各 Issue を補足します。ただし、ファイルパスや行番号は本文に含めないでください。古くなるためです。代わりに、振る舞いやコントラクトを説明します。

反証可能な受け入れ基準。 各基準について、それが誤りであることを示す観察結果を挙げ、実装担当者が着手するコミットで失敗することを確認します。次の 3 つの形式は受け入れません。ベースコミットですでに満たされている基準、別の Issue が担当する作業によってしか満たせない基準、依頼を言い換えただけの基準です。垂直スライスは、これまで存在しなかった振る舞いを実現するものなので、構成上、ベースコミットでは失敗するはずです。

Issue の形式：

Issue #N: [Title — a behaviour, not a layer]
---
Description: [What behaviour this delivers, end to end, and why]
Demo path: [The one thing you can show working when this lands]
Acceptance Criteria:
- [ ] [Falsifiable — names an observation that fails at the base commit]
- [ ] ...
Blocked by: [None / Issue #X, #Y]
Priority: [high / medium / low]
SPEC Reference: [Section X.Y — contracts only, no file paths; only if SPEC available]

---

ステップ 4：ユーザーに確認する（省略しない）

分解した内容を番号付きリストで提示し、何かを公開する前にユーザーに確認します。過剰な分割と、意図しない水平分割がよくある 2 つの失敗です。このステップで両方を防ぎます。

📋 Generated N Issues from [PRD/SPEC], in dependency order:

#1: Extract task-mutation helper (prefactoring) — Blocked by: none
#2: A user can set a task's priority and see it persist — Blocked by: #1
    demo: open a task, pick High, reload, still High
#3: A user can filter the task list to one priority — Blocked by: #2
    demo: select High, list shows only High tasks
#4: A user can sort the task list by priority — Blocked by: #2
    demo: click Sort, tasks reorder High→Low

Review before I create anything:
- Granularity: too fine? "merge #3 and #4". Too coarse? "split #2".
- Demo path: any Issue whose demo is a layer, not a behaviour, is mis-sliced — tell me.
- Edges: are the "Blocked by" links real? Any missing or spurious?
- Adjust: "change #2 priority to high", "add an issue for a priority badge"
- Confirm: reply OK to proceed

Issue を作成する前に、確認を待ちます。

---

ステップ 5：作成モードを選択する

Choose where to create these Issues:

A. GitHub (via gh CLI, with native blocking links and optional sub-issues)
B. Local (one markdown file per Issue, dependency-ordered)

Your choice:

---

ステップ 6：モードごとの作成

モード A：GitHub

前提条件： gh CLI がインストールされ、認証済みであること。--parent / --blocked-by を使用するには v2.94 以上が必要です。

依存する Issue の番号が必要になるため、ブロッカーを先に作成します。各 Issue で返された番号を記録します。

操作：

1. 各 Issue について、依存関係の順に：

   gh issue create \
     --title "[Title]" \
     --body "[Description + Demo path + Acceptance Criteria + SPEC Reference]" \
     --label "priority: [priority]" \
     --blocked-by [comma-separated blocker numbers, if any] \
     --parent [spec issue number, if creating as sub-issues]
   

   • 関係の指定には、ネイティブの --blocked-by を使用します。トラッカーがこのフラグを拒否する場合に限り、本文に「Blocked by #X」の行を記載します。
   • SPEC が GitHub issue にある場合は、--parent <spec_issue> を渡して、これらをその issue のサブ Issue にします。後から親を設定するには、gh issue edit <parent> --add-sub-issue <n> を実行します。
2. ラベルが存在しない場合は、先に作成するか、--label フラグを省略します。
3. 作成した Issue の番号と URL を報告します。

モード B：ローカル

ユーザーに確認します：

Where should I save the Issue files? (default: .autoresearch/issues/[feature-slug])

操作：

1. フィーチャーフォルダーが存在しない場合は、mkdir -p で作成します。フィーチャーごとにフォルダーを分けることで、並行するエージェントが共有ファイルを奪い合うのを防げます。
2. 各 Issue について、依存関係の順に NN-[slug].md を保存します（ゼロ埋めし、NN には /goal 03 が機能するよう、実際のチケット ID を使います）：

   # [Title — a behaviour]
   
   ## Description
   [What behaviour this delivers, end to end, and why]
   
   ## Demo path
   [The one thing you can show working when this lands]
   
   ## Acceptance Criteria
   - [ ] [Falsifiable criterion 1]
   - [ ] [Falsifiable criterion 2]
   
   ## Blocked by
   [None / #NN, #NN]
   
   ## Priority
   [high / medium / low]
   
   ## SPEC Reference
   [Section X.Y — contracts only; omit if no SPEC]
   

3. 作成したファイルパスを依存関係の順に報告します。

---

広範囲リファクタリングの例外

トレーサーバレットの原則に反するケースが一つあります。広範囲リファクタリングです。これは、列の名前変更や共有シンボルの型変更など、コードベース全体に影響が広がる単一の機械的な変更です。そのため、1回の編集で何千もの呼び出し箇所が壊れ、垂直スライスをどれもグリーンな状態でマージできません。

代わりに、expand → migrate → contractの順に進めます。

• Expand — 新しい形式を古い形式と並行して追加し、何も壊れないようにします。Issue は1つです。
• Migrate — 影響範囲に応じた単位（パッケージごと、ディレクトリごと）で呼び出し箇所をまとめて移行します。バッチごとに Issue を1つ作成し、それぞれを expand のブロック対象にします。古い形式が残っているため、CI はグリーンな状態を保ちます。
• Contract — 呼び出し元が残っていないことを確認したら、古い形式を削除します。この Issue は、すべての migrate バッチにブロックされるようにします。

各バッチだけではグリーンな状態を保てない場合は、共通の統合ブランチを使い、最後のintegrate-and-verify Issue がすべてのバッチにブロックされるようにします。グリーンであることを約束するのは、その Issue だけです。

---

ステップ 7：サマリーレポート

✅ Issue creation complete!

Source: [PRD/SPEC path]
Mode: [GitHub / Local]
Issues created: N (in dependency order)

#  | Title (behaviour)                        | Blocked by | Identifier
---|------------------------------------------|------------|------------
1  | Extract task-mutation helper             | —          | #42 / 01-*.md
2  | Set & persist task priority              | #1         | #43 / 02-*.md
3  | Filter task list by priority             | #2         | #44 / 03-*.md
4  | Sort task list by priority               | #2         | #45 / 04-*.md

Frontier (no open blockers, start now): #1

💡 Dispatch is manual — one Issue per fresh session, cleared between them.
   Count the Issues with no open blockers, open that many sessions, implement with /goal:
   /goal 42                # GitHub mode
   /goal 01-*.md           # Local mode
   Note: /goal may not auto-close the ticket — update its state yourself when done.

---

うまくいっている場合

• すべての Issue に「これが完了したら、何をデモできますか？」への答えがあります。その答えはレイヤーではなく、振る舞いです。
• 公開前に、実際の「Blocked by」行が各 Issue に付いた、番号付きのリストが返されています。
• 先頭の Issue にブロッカーがなく、すぐに着手できます。
• Issue の本文にファイルパスや行番号が含まれていません（プロトタイプが生成したスニペットを除く）。
• 各 Issue は、あなたが同席していなくても、新しいセッションだけで完了できる内容になっています。
• 見つかった場合、プレファクタリングは順序の先頭に置かれ、機能の Issue に混在していません。
• すべての受け入れ基準で、ベースコミットでは失敗する観察可能な結果が指定されています。

---

エッジケースとフォールバック

シナリオ	対応
変更全体が1つのコンテキストウィンドウに収まる	その旨を伝え、Issue を省略して、直接 /goal を案内します
tasks/ に PRD/SPEC が見つからない	ユーザーにファイルパスの提示、または要件の貼り付けを依頼します
PRD に User Stories がない	代わりに Functional Requirements から Issue を導き出します
SPEC に Issue Mapping（Section 10.2）がある	これを主な情報源として使用し、PRD と照合します
モデルがレイヤーごとに Issue を作成した	クイズで検出します。デモがレイヤーになっている Issue は、垂直スライスに分割し直します
モデルが過剰に分割した（3行の変更に12件のチケット）	クイズのステップで統合を提案します。全体が1つのウィンドウに収まる場合は、Issue を省略します
広範囲に及ぶ機械的なリファクタリング	上記の expand → migrate → contract の順序を使用します
gh が古く、--blocked-by / --parent に対応していない	「Blocked by」の本文行に切り替え、gh を v2.94 以降にアップグレードするよう提案します
GitHub モードで gh CLI が認証されていない	エラーを表示し、gh auth login を提案して、ローカルモードへの切り替えを案内します
ローカルモード用の Issue フォルダーが存在しない	機能ごとのフォルダーを自動作成します
ユーザーが Issue の作成を辞退した	依存関係順のリストをテキストのサマリーとして出力し、後で手動で作成できるようにします

---

他のスキルとの関係

/prd  →  /prd-to-spec (optional)  →  /to-issues  →  /goal  →  /review-it  →  /ship-it
 │              │                        │              │
 │  Requirements │  Technical design     │  Vertical    │  Implementation
 │  (what)       │  (how)                │  tickets     │  (code)

• /prd — PRD を作成します（このスキルへの入力）
• /prd-to-spec — SPEC を作成します（任意。このスキルと同じコンテキストウィンドウ内で使用します）
• /to-issues — 垂直スライスに分割した Issue を作成します（このスキル）
• /goal — Issue を1件ずつ、新しいセッションで実装します