# トラッカーイシューから MSD Core を操作する方法

**目標:** カスタムスクリプトやトラッカー連携なしに、MSD Core に既存のコマンドのみを使って、GitHub・Linear・Jira の単一の適切にスコープされたイシューを分離されたワークスペースからマージ済み PR まで通じたパイプラインで処理する。

**前提条件:** MSD Core がインストール済みであること。イシューは明確なスコープ、観察可能な受け入れ基準、上流のブロッカーがない状態であること。

このパターンの背景にある概念と設計理由については、[イシュー駆動オーケストレーションの説明](../issue-driven-orchestration.md)を参照してください。

---

## ステップ 1: イシューをフェーズにマッピングする

トラッカーイシューを開き、`ROADMAP.md` へのマッピングを決定します。

- **イシューが既存のフェーズと一致する** → フェーズ番号をメモしてステップ 2 に進む。
- **イシューがスタンドアロンの新しい作業** → フェーズを追加する：

```bash
/msd-phase "Description matching the issue title"
```

- **イシューが緊急で既存フェーズの間に挿入する必要がある** → 小数フェーズを挿入する：

```bash
/msd-phase --insert 3 "Fix: description from issue"
```

トラッカーイシューの URL をコピーします。ステップ 3 で `CONTEXT.md` に貼り付けることで、コンテキスト圧縮を経ても追跡可能性が維持されます。

---

## ステップ 2: 分離されたワークスペースを作成する

すべてのイシューには独自のワークスペース（独立した `.planning/` ディレクトリを持つ git ワークツリー）を用意します。部分的な作業、中断されたプラン、探索的なコミットを `main` の外に保ちます。

```bash
/msd-workspace --new --name my-issue-slug --repos . --strategy worktree
```

続行する前にワークスペースディレクトリに移動します。

```bash
cd ~/msd-workspaces/my-issue-slug
```

---

## ステップ 3: フェーズを議論する

計画が始まる前に実装上の決定を固定するために discuss-phase を実行します。セッションが開いたら、トラッカーイシューの URL を議論に貼り付けて `CONTEXT.md` に記録します。

```bash
/msd-discuss-phase N
```

MSD はイシューのスコープにある曖昧さ（エラーハンドリング、エッジケース、インターフェースコントラクト、技術選択）について質問します。回答がその後の計画を形作ります。

すべての答えがわかっていて素早く進みたい場合：

```bash
/msd-discuss-phase N --auto
```

---

## ステップ 4: フェーズを計画する

```bash
/msd-plan-phase N
```

MSD はリサーチエージェントを起動し、`CONTEXT.md` の決定（イシュー URL を含む）を読み込み、アトミックな `PLAN.md` ファイルを生成します。プランチェッカーが各プランを保存前に検証します。

実行前に外部 AI CLI からのピアレビューが必要な場合（重要な変更には推奨）：

```bash
/msd-review --phase N
/msd-plan-phase N --reviews
```

または、HIGH の懸念事項がなくなるまでプラン・レビュー・収束ループを実行するには：

```bash
/msd-plan-review-convergence N
```

---

## ステップ 5: フェーズを実行する

インタラクティブなフェーズ単位の実行の場合：

```bash
/msd-execute-phase N
```

すべての残りのフェーズをハンズオフで実行する場合：

```bash
/msd-autonomous
```

進捗を監視しながらフェーズ全体で作業を dispatch できるインタラクティブなダッシュボードの場合：

```bash
/msd-manager
```

3 つのアプローチすべてで `STATE.md` を更新し、各タスクをアトミックにコミットし、フェーズ後の検証を実行します。

---

## ステップ 6: 作業を検証する

```bash
/msd-verify-work N
```

MSD は（トラッカーイシューを反映した）フェーズゴールからの受け入れ基準を 1 つずつ確認します。何かが失敗した場合、MSD は根本原因を診断して修正プランを作成します。すべてのチェックが通るまで execute と verify を繰り返します。

コードが正しく見えても `verification_failed` はブロッカーとして扱ってください。失敗は通常、元のイシューからの見落とされた受け入れ基準を示しています。

---

## ステップ 7: レビューとリリース

PR を開く前にコードレビューを実行します。

```bash
/msd-code-review N
/msd-code-review N --fix
```

次に PR を作成します。

```bash
/msd-ship N
```

MSD は計画成果物（フェーズゴール、変更概要、対応した要件、検証ステータス、主要な決定）から PR ボディを組み立てます。PR がマージされた時にトラッカーイシューが自動的にクローズされるよう、PR ボディに `Closes #NNN` または `Fixes #NNN` を含めます（または `/msd-config` で設定）。

---

## ステップ 8: フォローアップ作業を記録する

イシューを進める中で関連する作業が見つかることがよくあります。コンテキストを失わずに記録します。

```bash
/msd-capture "Follow-up: description of discovered work"      # Todo として追加
/msd-capture --seed "Idea worth a future phase"               # 次のマイルストーン用に保存
/msd-capture --backlog "Not urgent but worth tracking"        # バックログに保存
```

MSD はトラッカーに自動的に投稿しません。記録されたフォローアップからトラッカーイシューを作成するのは手動の別ステップです。これにより人間のレビューをループに保ちます。

---

## 条件分岐

| 状況 | 対応 |
|-----------|-----------|
| イシューが非常に小さい（タイポ、設定変更） | ワークスペース + discuss + plan をスキップして `/msd-quick` を使用する |
| イシューに複数の独立したサブタスクがある | `/msd-manager` を使ってプラン全体で並行実行する |
| イシューが別のイシューにブロックされている | 上流のブロッカーが解決されるまで開始しない；MSD には自動的な依存ポーラーがない |
| 実行中にイシューのスコープが想定より大きくなった | 停止し `/msd-phase --insert N` でサブフェーズを追加して続行する |
| インタラクティブな議論をスキップしたい | `/msd-discuss-phase` に `--auto` フラグを使用するか、プロジェクト全体の自動化のために `workflow.skip_discuss: true` を設定する |
| 複数のイシューが一貫したリリースを形成する | `/msd-new-milestone` でグループ化し `/msd-autonomous` で順番に実行する |

---

## Related

- [イシュー駆動オーケストレーションの説明](../issue-driven-orchestration.md)
- [ワークスペースで作業を分離する](isolate-work-with-workspaces.md)
- [検証とリリース](verify-and-ship.md)
- [ドキュメント一覧](../README.md)