# Issue Report Dev

> Only use when the user explicitly invokes /issue-report-dev (or $issue-report-dev in Codex). Never auto-invoke. エンジニア自身が書く GitHub issue の起票スキル。ログ・スタックトレース・失敗テストを取り込み、サブエージェントでファイル/シンボル単位まで根本原因を調査し、原因の仮説・修正方針案・受入条件まで含む issue を起草する。技術的な質問と期待仕様の確認を制限なく行い、想定変更領域の重なりでグルーピングして登録・統合する。非エンジニアからの報告受付は issue-report-user を使う。

- Skill: `efoo-team/issue-report-dev` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add efoo-team/issue-report-dev`
- Raw SKILL.md: https://api.skillmd.com/api/skills/efoo-team/issue-report-dev/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: efoo-team (https://skillmd.com/u/efoo-team)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/efoo-team/issue-report-dev

---


# issue-report-dev

エンジニア自身の不具合報告・改善要望を複数まとめて受け付け、根本原因の調査と技術的なヒアリングで具体化し、コンフリクトしない単位にグルーピングして GitHub issue として登録・統合するスキル。

## 目的

`issue-report-user`（非エンジニアの報告者向け）と同じ「1 issue = 想定変更領域が独立している単位 = ワークツリー1本の分割単位」という編成方針を共有しつつ、**報告者がエンジニアであることを前提に、issue の技術的な精度を最大化する**。具体的には次の3点を `issue-report-user` に対して上乗せする:

1. **根拠つきの原因仮説** — スタックトレース・ログ・コードの読み取りから、原因候補をファイル・シンボル単位まで絞り、根拠を添えて記載する
2. **修正方針案** — 想定される修正アプローチを複数案とトレードオフで記載する（案であって決定ではない）
3. **受入条件** — 着手者がそのまま実装に入れる粒度で、完了判定の基準を明文化する

本スキルは control plane として動作する。parent は PM としてユーザー対話・ゲート・進行管理・成果物ファイルの受け渡しだけを担い、分解・調査・照合・グルーピング・起草・登録の実作業はワーカー（環境が提供するサブエージェント機構）へ委譲する。

## 想定ユーザー

このスキルを起動するのはエンジニアである前提で振る舞う。**技術用語・ファイルパス・シンボル名・コード引用・コミットハッシュを制限なく使ってよい**。報告者はログ・スタックトレース・失敗テスト出力・コマンド出力・ブランチ名・PR 番号を提示できるものとして扱い、必要なら遠慮せず要求する。

報告者が非エンジニアの場合は本スキルを使わず `issue-report-user` を使う（技術的な質問を避け、画面の言葉だけでヒアリングするスキルである）。

## 追加指示の扱い

ユーザーが引数として渡した内容（Claude では `/issue-report-dev` の引数、Codex では `$issue-report-dev` の引数）は、問題や要望の最初の説明として扱い、本スキル内の他の方針より優先して適用する。ただし「承認なしに GitHub へ書き込まない」「実装仕様を確定しない」「コードを編集しない」などの重要な制約に反する場合は、実行せず直ちに停止して確認を求める。引数が空の場合は、「起票したい不具合・要望を挙げてください。複数まとめて構いません。ログやスタックトレースがあればそのまま貼ってください」から始める。

## 最重要遵守ルール

1. **技術的な質問を制限しない**。期待仕様・設計意図・再現条件・制約・原因の心当たりを遠慮なく尋ねる。これは `issue-report-user` との最大の差分であり、あちらの「技術用語を使わない」制約は本スキルには適用されない
2. **すべての質問はスキップできる**。質問のたびに「わからない・未定で構いません」と明示し、答えが得られなかった項目は `不明` または `未定` と正直に書く。推測で埋めない
3. **原因の仮説には必ず根拠を添える**。根拠はファイルパス・シンボル名・行範囲・テスト名・ログの該当行など、読み取りで確認できた事実に限る。確認できていない推測は「未検証の仮説」として根拠つき仮説と**区別して**書く
4. **修正方針は案であり決定ではない**。実装仕様・設計の確定と実装は行わない（確定は `/define` 以降の工程の責務）。issue には案とトレードオフを併記し、単一の解を指示する書き方をしない
5. **`touchAreas` の粒度は領域単位（画面 / ルート / モジュール / ディレクトリ prefix）を維持する**。根本原因をファイル・シンボル単位まで特定しても、グルーピング判定の入力である `touchAreas` は細かくしない。判定規則が領域単位の重なりを前提に設計されており、入力を細分化すると干渉を検出できず、並列開発でコンフリクトする分割を生む。ファイル単位の特定結果は `rootCause.evidence` に入れる
6. **parent は PM に徹する**。ケース分解・コード調査・既存 issue 照合・グルーピング・本文起草・登録実行の実作業を parent が抱え込まない。ワーカー間の成果物はすべてファイルで受け渡し、parent はパスと件数サマリーのみ保持する
7. **ユーザーの明確な承認を得るまで GitHub へ一切書き込まない**。承認は Phase 7 の登録計画に対して行う
8. **コード調査は読み取り専用**。ソースコード・設定ファイルの編集・作成・削除は行わない（実行ディレクトリ配下の成果物ファイルは例外）
9. **確認待ちラベル `needs-triage` は付与しない**。このラベルは「非エンジニアの報告をエンジニアが確認するまでのゲート」であり、エンジニア自身が調査して起票する本スキルの issue では既に満たされている

## 共通プロトコルからの差分

パイプラインの構造（Phase 0〜7）・成果物ファイルのスキーマ・ゲート条件・グルーピング判定・登録時の安全規律は、`issue-report-user` の references を**共通正本**として参照する（[参照ドキュメント](#参照ドキュメント)）。本節はそこからの差分だけを宣言する。**共通正本の記述と本節が食い違う場合は本節が優先する。**

| Phase | 共通プロトコル | 本スキルの差分 |
|---|---|---|
| 0 受け取り | 報告原文を `report.md` へ保存 | ＋貼り付けられたログ・スタックトレース・失敗テスト出力・コマンド出力を `artifacts/` へ**原文のまま**保存し、`report.md` からはパスで参照する（parent のコンテキストへ全文を展開しない） |
| 1 ケース分解 | 差分なし | 差分なし。1行要約は技術表現のままでよい |
| 2 調査 | 領域単位の調査 | ＋根本原因の深掘り（後述）。`investigation-<id>.json` に本スキル固有フィールドを追加 |
| 3 特定確認 | 画面の言葉で提示 | 技術表現（パス・モジュール名）で提示してよい。確度 `high` は一覧表で一括確認、`low` のみ個別対話 |
| 4 ヒアリング | 平易な質問のみ・技術的質問を避ける | 技術的質問と期待仕様の確認を行う（後述の質問セット）。全質問スキップ可 |
| 5 グルーピング | `grouping-rules.md` を適用 | 差分なし（同一規則をそのまま適用する） |
| 6 起草 | `issue-format.md` のテンプレート | `references/issue-format-dev.md` のテンプレートを使う。共通規約（「対象領域:」定型行・更新履歴）と統合時の本文書き換え手順は `issue-format.md` に従う |
| 7 承認・登録 | `needs-triage` を必ず付与 | **`needs-triage` を付与しない**（後述） |

### Phase 2 差分: 調査ワーカーへの依頼

共通プロトコルの依頼内容に加えて、担当ケースについて次を読み取り専用で調べさせる。`artifacts/` に該当ケースの資料があればそのパスも渡す。

- **エラーからコードへの到達**: スタックトレース・エラーメッセージ・ログの文言から該当コードを特定し、呼び出し経路をたどって原因候補を**ファイル・シンボル・行範囲**まで絞る
- **変更履歴の確認**: 原因候補付近の直近の変更を `git log`（`-S` / `-L` / blame 等）で確認し、関連するコミット・PR・過去 issue があれば特定する
- **既存テストの有無**: 当該挙動を固定しているテストがあるか。あればテスト名とパス
- **期待仕様の根拠**: 型定義・スキーマ・設定・ドキュメント・コメントに、あるべき挙動を示す記述があるか
- **修正方針の候補**: 原因仮説が立った場合に限り、想定される修正アプローチを**複数案**、それぞれの影響領域とトレードオフ（副作用・移行コスト・後方互換）とあわせて起こす
- **受入条件の候補**: 何が満たされれば解決と言えるかを、検証可能な形（観測できる挙動・テスト観点）で起こす

制約:

- **`touchAreas` の粒度は領域単位のまま**にする（最重要遵守ルール5）。ファイル単位の特定は `rootCause.evidence` へ入れる
- 読み取りで確認できた事実と推測を必ず区別する。確認できていないものは `rootCause.unverified` に入れ、`evidence` には入れない
- 原因を特定できなかった場合は「特定できず」と返す。もっともらしい仮説をでっち上げない
- ソースコード・設定ファイルの編集は禁止（出力は成果物 JSON のみ）

### Phase 4 差分: ヒアリング質問セット

parent が調査ワーカーの `missingInfo` と `rootCause.unverified` を優先度順に束ね、不足している項目だけを質問する。利用可能な質問機能で一度に最大4問。**各質問に「わからない / 未定」の選択肢を必ず含める**（調べれば分かるが今は答えられない、という項目は「未定」で先へ進んでよい）。

**不具合系（kind: bug）:**

| 聞くこと | 質問の例 |
|---|---|
| 期待仕様 | 本来どう動くべきですか？ その根拠（仕様書・設計意図・過去の合意・型やスキーマ）はありますか？ 未定なら「未定」で構いません |
| 再現条件 | 再現するブランチ・コミット・環境・データ条件は？ 100% 再現しますか？ |
| 技術資料 | 手元にログ・スタックトレース・失敗するテストがあれば貼ってください |
| 影響と緊急度 | どの環境の誰に影響していますか？ 本番影響・データ不整合はありますか？ |
| 原因の心当たり | 疑っている箇所・直前の変更に心当たりはありますか？ |
| 制約 | 修正時に守るべき制約（後方互換・締切・触ってはいけない領域）はありますか？ |

**要望系（kind: request）:**

| 聞くこと | 質問の例 |
|---|---|
| 期待仕様 | 実現後はどう振る舞うべきですか？（入出力・境界条件・エラー時の挙動） 未定なら「未定」で構いません |
| 目的・背景 | 何のために必要ですか？ 現状の何が問題ですか？ |
| 既存仕様との関係 | 変更・置き換えになる既存の挙動はありますか？ 互換性を保つ必要はありますか？ |
| 受入条件 | どうなれば「できた」と言えますか？ |
| 制約 | 移行・性能・セキュリティ・運用上の制約はありますか？ |

回答（「不明」「未定」を含む）は parent が `hearing-<id>.json` に記録する。ユーザーが回答の中で新しい技術情報（ログ等）を提示した場合は `artifacts/` へ保存し、必要なら該当ケースの調査ワーカーを再起動してよい。

### Phase 7 差分: ラベル

- **`needs-triage` を作成も付与もしない**。Phase 7-2 のラベル事前準備の対象は、横断グループが1つ以上ある場合の `scope:cross-cutting` のみとする。したがって「必要なラベルを用意できなかった場合は実行ワーカーを起動しない」という共通プロトコルの停止条件も、本スキルでは `scope:cross-cutting` が必要な場合にのみ適用される
- 種別ラベル（bug / enhancement 相当）と `scope:cross-cutting`（該当時）の付与規律・付与後の検証手順は共通プロトコルのとおり
- 登録計画の提示（Phase 7-1）と完了報告（Phase 7-3）から、確認待ちラベルに関する案内文は削除する

## 成果物スキーマの拡張

`investigation-<id>.json` に次のフィールドを追加する。共通プロトコルのフィールド（`screenCandidates` / `touchAreas` / `confidence` / `missingInfo` / `intentSignals`）は**そのまま維持する**（分類エージェントと共通の照合処理が使うため）。

```json
{
  "rootCause": {
    "hypothesis": "並び替え時に一覧キャッシュを破棄せず再取得結果を捨てている",
    "confidence": "high",
    "evidence": [
      { "path": "src/features/order-history/useOrderList.ts", "symbol": "useOrderList", "lines": "88-104", "note": "sortKey が deps に無く再フェッチ結果が破棄される" },
      { "path": "src/features/order-history/__tests__/useOrderList.test.ts", "symbol": "sorts by date", "lines": "42-58", "note": "現在の挙動を固定している既存テスト" }
    ],
    "unverified": ["同一事象がサーバー側のキャッシュヘッダに起因する可能性は未確認"],
    "relatedCommits": ["a1b2c3d (PR #321)"]
  },
  "fixApproaches": [
    { "summary": "sortKey を deps に加える", "affectedAreas": ["注文履歴画面"], "tradeoffs": "最小変更だが再フェッチ回数が増える" },
    { "summary": "並び替えをクライアント側で行い再取得しない", "affectedAreas": ["注文履歴画面", "共通データ取得層"], "tradeoffs": "通信は減るが全件取得が前提になり件数増加に弱い" }
  ],
  "acceptanceCriteria": [
    "並び替え操作後、表示中の一覧が選択した順序で並ぶ",
    "既存テスト sorts by date が現行仕様のまま通る、または仕様変更として更新される"
  ],
  "reproTechnical": {
    "steps": ["注文履歴を開く", "日付で並び替える"],
    "environment": "app v2.14.0 / Node 22.11 / Chrome 141",
    "branchOrCommit": "main@a1b2c3d",
    "artifacts": ["artifacts/c1-stacktrace.log"],
    "frequency": "100%"
  }
}
```

- `rootCause.confidence`: `high` | `low` | `none`（特定できず）。`none` の場合 `hypothesis` は空にし、調べた範囲を `unverified` に残す
- `evidence` は**読み取りで確認できた事実のみ**。推測は `unverified` へ
- `fixApproaches` は原因仮説が立った場合のみ。1案しか無い場合も「他案なし」と分かる形で1件だけ書く
- `reproTechnical.artifacts` は `artifacts/` 配下のパス。ログ本文を JSON へ展開しない

## サブエージェントが無い環境での縮退

サブエージェント機構を提供しないハーネス（例: Codex）では、役割分離を parent 1体の中で縮退実行する。共通プロトコルの縮退規律と同じく、フェーズ分離（分解 → 調査 → 確認 → ヒアリング → グルーピング → 起草 → 承認 → 登録）を作業規律として保ち、承認前に書き込みを混ぜない。成果物ファイルは縮退時も同様に作成し、過去フェーズの詳細はファイルを正本として必要時に再読する。登録実行は「1 issue 操作ずつ」順に行う。

縮退時に特に崩れやすいのは最重要遵守ルール3（根拠と推測の区別）である。自分で調査し自分で起草するため、確認していない推測が根拠つき仮説の顔をして本文に混入しやすい。`rootCause.evidence` に書く前に「このファイル・行を実際に読んだか」を毎回確認する。

## 参照ドキュメント

共通正本3本は `issue-report-user` 側にある（両スキルで共有し、片方の都合で変更しない）。実行時は該当ファイルを直接参照すること。

- **オーケストレーション詳細プロトコル（Phase 0〜7）**: [`../issue-report-user/references/orchestration-protocol.md`](../issue-report-user/references/orchestration-protocol.md)
  - 実行ディレクトリと成果物ファイルのスキーマ / 各フェーズの parent の仕事とワーカー依頼内容 / ユーザー対話のスケール設計 / 実行ワーカーの規律（統合先の直前再検証・ラベル付与の検証）
- **グルーピング規則**: [`../issue-report-user/references/grouping-rules.md`](../issue-report-user/references/grouping-rules.md)
  - 想定変更領域（touch set）の定義 / 重なり判定 / 横断領域の扱い / 既存 issue 照合規則（open 参照 PR による統合先不適格の判定）
- **issue 本文の共通規約と書き換え手順**: [`../issue-report-user/references/issue-format.md`](../issue-report-user/references/issue-format.md)
  - 「対象領域:」定型形式 / 任意定型行 / 更新履歴 / 既存 issue 本文の書き換え（統合）手順。**本文テンプレートは本スキルでは使わない**
- **本スキルの issue 本文テンプレート**: [`references/issue-format-dev.md`](references/issue-format-dev.md)
  - 不具合用・要望用の単一ケース形式 / 複数ケース形式 / 原因仮説・修正方針案・受入条件の書き方

> 共通正本への依存は相対パス（`../issue-report-user/`）で解決する。両スキルは同じリポジトリから同じディレクトリ配下へ配布されるため、リポジトリ上でもインストール先（`~/.agents/skills/`）でも同じ相対関係になる。**どちらかのスキルを改名・移動するときは両方を同時に更新すること**（リンク切れは `check-skills.py` では検出されない）。

## 重要な制約

- ユーザーの明確な承認（Phase 7 の登録計画への承認）を得るまで GitHub へ書き込まない。承認後に許可される書き込みは以下の3種のみとし、それ以外の書き込み操作（issue のクローズ・コメント投稿・アサイン等）は行わない:
  - `gh issue create`（新規登録）
  - 承認済みの統合先に対する `gh issue edit <番号> --body`（本文書き換えによる統合）
  - ラベル付与（種別ラベル、`scope:cross-cutting`。後者が存在しない場合の `gh label create` を含む。`needs-triage` は付与しない）
- ソースコード・設定ファイルの編集・作成・削除は行わない（実行ディレクトリ配下の成果物ファイルは例外）
- 実装仕様・設計を確定しない。修正方針は複数案とトレードオフの形で提示し、採否の判断は着手者・後段の要件定義工程に委ねる
- 根拠を確認していない推測を、根拠つきの仮説として書かない
- 質問への回答を強制しない。答えが得られない項目は `不明` / `未定` と明記する
- 統合（本文書き換え）では既存 issue の記載内容を削除・要約しない。既存の記載は全て保持したままケースを追加する
- **gh コマンドが使えない・認証されていない場合**: エラーで止めず、登録計画（タイトルと本文）をコピーできる形で提示し、手動登録（GitHub の Issues → New issue → 貼り付けて Submit）を案内する