update-issue

name	update-issue
description	Update an existing GitHub Issue's description based on the issue number. Reads all issue comments and reflects any items not yet captured in the description. After refreshing the description, reviews it for remaining ambiguities or unclear requirements and posts any open questions as a follow-up 確認事項 comment.
argument-hint	[Issue番号]
hooks	{"Stop":[{"matcher":"","hooks":[{"type":"command","command":"docker compose down --volumes --remove-orphans"}]}]}

Update Issue

引数で受け取ったIssue番号をもとに、Issueのコメントを全件読み取って文脈を把握し、まだdescriptionに反映されていない事項を反映するスキル。Instructionsに従い、Issueの内容とコメントの確認、コードの分析、descriptionの更新を行う。

責務の分担: 本スキルは「既存Issueとコメント取得・未反映事項の抽出・コード分析・既存『依頼内容』ブロックが保持されたことの事後確認」までを担い、「本文整形・投稿前チェック・既存変更ログの verbatim 再掲・既存依頼内容ブロックの verbatim 再掲・gh issue edit 実行」は post-issue-body スキルへ委譲する。本文テンプレート・変更ログ追記ルール・投稿前チェックリスト・heredoc 投稿コマンドはすべて post-issue-body 側に集約されているため、本スキル内では再記述しない。

「依頼内容」の扱い: 本スキルの役割は「コメントから拾った未反映事項の反映」であり、依頼内容ブロック（<details><summary>依頼内容</summary>）を新規作成しない。既存bodyを丸ごと依頼内容として複写すると、更新後 description で元本文と反映後本文が二重に残るため。「人が最初に書いた原文」を残す用途は create-issue-from-issue-number の責務であり、本スキルはそこに触れない。ただし、すでに依頼内容ブロックが存在する Issue（旧フォーマットの裸の ## 依頼内容 見出しも含む）に対しては、その中身を verbatim で再掲して失わないよう引き継ぐ（旧フォーマットは post-issue-body 側が折りたたみブロックへ詰め替える）。コメントで依頼内容そのものの書き換え要望が来ても依頼内容ブロックは書き換えず、コメント由来の変更は 概要 要件 実装プラン 側で反映する。

Instructions

実行モードの制約: サブエージェント・サブスキル・Bashをバックグラウンド実行しないこと

本スキルは claude-task-worker の cc-update-issue ラベルをトリガーに自動起動される想定で、ワーカーはスキルプロセスの同期完了を根拠にラベル遷移や後続ワーカー起動を進める。本スキル内部で呼び出す Agent / Skill / Bash を絶対にバックグラウンド実行しないこと。

• Agent ツールは既定が run_in_background: true（バックグラウンド）。呼び出しごとに 必ず run_in_background: false を明示指定 し、フォアグラウンドで同期的に結果を受け取ってから次の処理に進む。指定を省略した場合はバックグラウンドで走り、本スキルが未完のまま終了する。特に Explore サブエージェントは並列起動時も個別に run_in_background: false を指定する
• Skill に run_in_background: true を指定しない（既定は同期）。特に post-issue-body は投稿完了を受け取ってから次のステップに進む
• 同一メッセージ内で複数の Agent / Skill を並列に投げるのは「並列実行」であって「バックグラウンド実行」ではないため許容される（各サブエージェントの完了はその場で同期的に待つ）
• Bash にも run_in_background: true を指定しない。コマンド末尾に & を付けたり、nohup / disown / setsid でデタッチしたりしない
• ScheduleWakeup などで処理を後回しにしない

理由: バックグラウンド化すると子処理の完了前に本スキルが終了し、ワーカーが「正常完了」と誤認して cc-update-issue を外すため、後続の answer-issue-questions / triage-created-issue / exec-issue などが古い description を前提に起動されてしまう。内部処理はすべて同期実行で完結させる。

実行ステップ

1. 作業ディレクトリの確認とデフォルトブランチの同期

pwd で現在地を確認する。.claude/worktrees/ 配下にいればそのworktree内で、それ以外（リポジトリのルート等）ではその場で作業する。worktreeを新たに作成しないこと。

デフォルトブランチの最新化は以下を試行し、失敗しても中断せずスキップして続行する（本スキルはコードを変更しないため）。

git fetch --prune || true

git rebase や git pull は実行しない（未コミット変更や conflict による中断を避けるため）。

2. 既存Issueの取得

引数から先頭のIssue番号を取り出し、そのIssueを取得して現在の内容を確認する。

gh issue view <Issue番号> --json number,title,state,labels,body,url

なお、変更ログの verbatim 再掲用の既存本文取得は post-issue-body が mode=edit で再度行うため、本ステップの body は分析用途（差分検出）で使い、post-issue-body へは Issue 番号だけを伝えればよい。

コメントの取得（必須）

コメント全件が更新の唯一の入力になるため、必ず併せて取得する。

gh issue view <Issue番号> --comments

本文・コメントに画像URLがある場合、gh-asset でダウンロードして内容を読む。テキストだけでは伝わらない仕様（UIの見た目・エラー画面・図など）がdescription更新の判断に必要なことがあるため、URLを見て終わりにせず、ダウンロードした画像を実際に Read で確認する。

gh-asset download <asset_id> ~/Downloads/

参考: https://github.com/YuitoSato/gh-asset

2.5. 既存「依頼内容」ブロックの検出（新規作成はしない）

ステップ2で取得した body に、既に依頼内容ブロックがあるかどうかだけを確認する。ある場合はその存在と中身を記録し、無い場合は「無し」として扱う。本スキルは依頼内容ブロックを新規作成しない。

• 既存bodyに <details><summary>依頼内容</summary> ブロックが存在する場合（create-issue-from-issue-number が過去に新フォーマットで書き込み済み）
  • verbatim 再掲は post-issue-body 側が担当する（args.sections.依頼内容 を未指定にして呼べば、mode=edit で既存bodyの中身が verbatim 再掲される規約）。したがって本スキルからは 依頼内容 を渡さない。
  • ステップ5.5の事後検証用に、切り出した中身（<summary>依頼内容</summary> の閉じタグ直後から </details> の直前まで、タグは含めない。先頭・末尾の空行1つは正規化してよい）を「期待値」として保持しておく。
• 既存bodyに旧フォーマットの ## 依頼内容 見出しがある場合（本フォーマット移行前の Issue）
  • 同じく本スキルからは 依頼内容 を渡さない（post-issue-body 側が旧フォーマットを検出して折りたたみブロックへ詰め替える）。ステップ5.5の期待値は、見出し直後から次の ## 見出しまたはEOF直前までの中身を切り出して保持する。
• どちらも無い場合 — 何もしない。依頼内容ブロックは無いままにする（更新後 description は従来通り ## 概要 から始まる6セクション構成になる）。

完了条件: 期待値の「依頼内容」文字列（存在する場合はその中身、無い場合は「なし」フラグ）と、期待される書き出しフォーマット（常に <details><summary>依頼内容</summary> の折りたたみ）が確定していること。

3. タスクの分析

ステップ2で取得したコメント全件を入力として扱う。各コメントを時系列で読み、確認事項への回答・仕様変更・追加要望などを洗い出したうえで、既存descriptionと突き合わせ、まだ反映されていない事項を今回の更新対象とする。

• 既にdescriptionへ反映済みの内容は本文・変更ログともに再掲のみとし、重複した変更を加えない
• コメントが本文と矛盾する場合は、より新しいコメントの合意を優先する
• 反映すべき未反映事項が1件も無い場合は、descriptionを更新せず（ステップ5の post-issue-body 起動をスキップ）、その判断をユーザーに報告して終了する

加えて、タスクの内容を理解するために、要件定義ドキュメントやデザインファイル（Pencilファイル）を読み込み、タスクの背景・目的・関連する仕様を把握する。Pencilファイル（.pen）は inspect-pencil-node スキルで対象Nodeの属性データとスクリーンショットを取得して内容を確認すること（.pen は暗号化バイナリで Read/Grep は使えない）。.pen の編集が必要と判明した場合は本スキル内では編集せず、post-issue-body へ渡す「実装プラン」「確認事項」に「pencil-design-updater エージェントで <対象 .pen> を更新する」旨を明記して後続タスクへ委譲する。

4. コードの分析

Explore サブエージェントで未反映事項に基づき、コードベースをできるだけ詳細に分析する。 ユーザーへの確認が必要な事項があっても途中で質問せず、Issue へ確認事項として残す（post-issue-body へ「確認事項」として渡せばコメントとして投稿される）。

直近関連変更の確認（必須）

進行中・直近完了済みの関連作業を見落とし、既存実装と重複するゴーストタスクを含んだ Issue に更新しないため、対象ファイル一覧について直近の commit 履歴と関連 PR を必ず確認する。

• 対象ファイルごとに git log --oneline -10 <file> を実行し、直近 commit のサマリを把握する
• gh pr list --search "<file>" で未マージの関連 PR を確認する
• 直近 commit に大規模リファクタ・共通ヘルパー追加などの大きな変更が含まれる場合や、未マージの関連 PR がある場合は、その内容を post-issue-body に渡す「直近関連変更」セクション（必要に応じて「参照情報」にも）に必ず記載し、実装プランが既存実装と重複していないか検証する
• git 履歴のない新規機能要求など確認が困難なケースでは「該当なし」と記載してスキップしてよい

4.5. 反映後 description の曖昧点レビュー（確認事項の補強）

ステップ3〜4で反映内容（更新後の 概要 要件 実装プラン など）が固まったら、その内容を「実装者がそのまま着手できる解像度になっているか」という観点で読み直す。コメントを反映してもなお、要件が曖昧・前提が未確定・複数の解釈が残る箇所があれば、それを確認事項として洗い出す。

descriptionは実装者や後続スキル（exec-issue など）が着手時の唯一の入力になるため、曖昧なまま更新すると気づかれずそのまま手戻りになる。反映で埋めきれなかった不明点をその場で質問に変換してコメントに残しておけば、着手前に人が答えられる状態を作れる。これがこのステップの狙いで、descriptionを「更新して終わり」にせず「更新した内容の穴を突く」ことに価値がある。

洗い出す観点の例:

• 要件の受け入れ条件（どうなれば完了と言えるか）が本文から判断できない
• コメント同士、またはコメントと既存本文で結論が食い違い、どちらを採るか確定できない
• 実装プランの分岐（対象範囲・非対応ケース・既存挙動との整合）が仕様として未確定
• ステップ4のコード分析で前提と既存実装が食い違い、意図を確認しないと進められない

ここで洗い出した確認事項は、ステップ4で既に把握していた未確認事項とマージして重複を除いたうえで、ステップ5で post-issue-body の confirmation_items としてまとめて渡す（post-issue-body がそれらを1つの ## 確認事項 コメントとして投稿する）。コメントを二重に投稿しないよう、確認事項の投稿口はこの confirmation_items に一本化する。

曖昧点が本当に無ければ confirmation_items は省略してよい（穴埋めのために無理に質問を作らない — 中身の薄い確認事項はノイズになり、かえって着手を遅らせる）。なお、途中でユーザーへ直接質問せず必ずコメントに残す方針は本スキル全体で共通（ステップ4の注記と同じ）。

5. post-issue-body スキルで Issue を更新

ステップ2〜4.5の分析結果を 以下の YAML ブロックの形でそのまま args として Skill tool で post-issue-body を起動する（post-issue-body は args を YAML として機械的にパースする規約）。

mode: edit
issue_number: <ステップ2で確定した番号>
title: <更新後タイトル — 変えない場合はステップ2で取得した既存タイトルを再掲>
sections:
  概要: |
    （1-3行、コメント由来の更新を反映）
  要件: |
    - ...
    （無ければ "なし"）
  参照情報: |
    - ドキュメント: `<path>` — <説明>
    （無ければ "なし"）
  直近関連変更: |
    - `<commit hash>` <subject> — <影響>
    （ステップ4で確認した結果、無ければ "該当なし"）
  実装プラン: |
    1. （コメント反映後の最新版）
  影響範囲: |
    - `<path>` — <概略>
new_changelog_entry: コメントの〇〇を要件に反映  # コメントから反映した内容が分かる粒度で1行
confirmation_items:  # ステップ4の未確認事項＋ステップ4.5の残曖昧点をマージ（重複除去）。0件ならキーごと省略
  - <ステップ4で新たに発生した未確認事項、またはステップ4.5で洗い出した反映後の残曖昧点>

sections.依頼内容 は本スキルからは絶対に渡さない。ステップ2.5のとおり、既存の依頼内容ブロック（新旧フォーマットとも）の verbatim 再掲は post-issue-body 側の責務（args.sections.依頼内容 未指定なら既存bodyの中身を verbatim 再掲する規約）。既存bodyに依頼内容が無ければ追加もしない。コメントで発生した仕様変更は 概要 要件 実装プラン 側で反映する。

Skill tool 呼び出しは Skill(skill='post-issue-body', args=<上記YAML文字列>)（必要なら plugin namespace 付きで base-tools:post-issue-body）。args は改行を含む複数行文字列としてそのまま渡す。post-issue-body の責務範囲は以下のとおりで、本スキルから重複して実行しない。

• gh issue view --json body で既存本文を再取得して変更ログを verbatim で再掲
• 本文テンプレート・投稿前チェックリストに従って本文を組み立て・検証
• gh issue edit で更新（--remove-label は不使用）
• 確認事項が渡されていればコメント投稿

完了後、Issue URL と確認事項コメントの有無が返ってくる。未反映事項が0件と判断した場合は post-issue-body を起動せず、その旨をユーザーに報告して終了する。

5.5. 既存「依頼内容」ブロックが失われていないかの事後検証

post-issue-body は本文全体を heredoc で上書きするため、verbatim 再掲ロジックのバグや漏れで元の依頼原文が消える可能性がある。本スキルは依頼内容ブロックを新規作成しないが、既に存在した依頼内容を失わせない責任は本スキルにあるので、投稿完了直後に検証する。

以下を機械的に実行する（ユーザーへの確認は不要）:

• ステップ2.5で「既存bodyに依頼内容が無い」と判定した場合 — 本ステップはスキップする（保護対象が無い）。
• 未反映事項が0件で post-issue-body の起動をスキップした場合 — 本ステップもスキップする（description を更新していないため）。
• ステップ2.5で「既存bodyに依頼内容あり」と判定した場合 — 以下の手順で検証する:
  1. gh issue view <issue_number> --json body -q .body で更新後の body を取得する。
  2. 取得した body から <details><summary>依頼内容</summary> ブロックの中身を抽出する（<summary> の閉じタグ直後から </details> の直前まで、タグは含めない。先頭・末尾の空行1つは正規化してよい）。本文中に <details> は依頼内容と変更ログの2つ存在し得るので、必ず <summary>依頼内容</summary> で識別してから切り出す。
  3. ステップ2.5で保持した「期待値」と抽出した中身を比較する。改行・空白まで含めて完全一致すること。前後の空行1つ程度の差は許容してよいが、内容の欠落・改変は不可。
  4. 書き出しが折りたたみブロックになっていること — 実行前が旧フォーマット（## 依頼内容 見出し）だった場合も、更新後は必ず <details><summary>依頼内容</summary> に詰め替わっていること。裸の見出しのままなら逸脱として扱う。
  5. 一致しない、または折りたたみになっていない場合は次の順で復旧を試みる:
     • もう一度 post-issue-body を同じ args で呼び直す（一過性の投稿エラーの可能性）。
     • 再実行後も一致しない場合は、gh issue view --json body で取得した現在の body に対して「## 概要 の直前に <details>\n<summary>依頼内容</summary>\n\n<期待値>\n\n</details>\n\n を差し込んだ本文」を組み立て、gh issue edit <issue_number> --body-file - <<'EOF' ... EOF で直接上書きする。既存に旧フォーマットの ## 依頼内容 見出しや別の依頼内容ブロックが残っていれば、その部分は取り除いてから差し込む。
     • どちらでも解消しなければ、Issue URL と失敗理由を最終報告に含めて終了する（サイレント失敗させない）。
  6. 検証が通れば、Issue URL・確認事項コメントの有無・依頼内容保護検証結果（一致 / 復旧して一致 / 未一致（要手動確認））をまとめて報告して終了する。

完了条件: 実行前bodyに依頼内容があった場合は更新後bodyでもその中身が <details><summary>依頼内容</summary> ブロックとして保持されていること（または未反映事項0件・依頼内容無しで本ステップをスキップした状態）。

中断条件

• 引数が空、または Issue 番号として解釈できない
• gh issue view で対象 Issue が見つからない、または CLOSED
• post-issue-body が失敗し、再試行しても解消しない
• ステップ5.5の既存「依頼内容」保護検証で、post-issue-body 再実行と直接 gh issue edit によるフォールバックの両方に失敗した場合 → Issue URL・失敗理由・保持されるべき「依頼内容」期待値を出力して終了（サイレントに終わらせない）

注意事項

• このスキルはコードを一切変更しない。Issue の更新・コメントは原則 post-issue-body 経由で行う（本スキル内で直接 gh issue edit を呼ぶのはステップ5.5のフォールバック用途に限る）
• 途中でユーザーに質問しない。確認したいことは post-issue-body へ「確認事項」として渡し、コメントとして残す
• description を反映しただけで終わらせず、ステップ4.5で「反映後もなお残る不明点・曖昧な要件」を見直し、あればステップ4の未確認事項とマージして confirmation_items として渡す（## 確認事項 コメントに一本化する。曖昧点が無ければ無理に作らない）
• 依頼内容ブロック（<details><summary>依頼内容</summary>）を新規追加しない（理由は冒頭「『依頼内容』の扱い」を参照）
• 既存bodyに依頼内容ブロックがあった場合、その保持は post-issue-body の verbatim 再掲規約に委ねる。args の sections.依頼内容 は本スキルからは渡さない（渡すと原文とのズレを生む可能性がある）。ステップ5.5で実際に保持されかつ折りたたみで書き出されたかを検証する
• Pencil ファイル（.pen）の読み込みは inspect-pencil-node スキル経由でのみ行う（暗号化バイナリのため Read/Grep は使えない）
• .pen の編集は本スキルでは絶対に行わない。必要と判明した場合は pencil-design-updater エージェントで対応する旨を post-issue-body 経由で「実装プラン」または「確認事項」に明記して後続タスクへ委譲する（.pen 編集は pencil-design-updater 専任・edit-pencil-design スキル経由の運用 — 同パス上書き・差分Node特定・snapshots/ 出力 — に集約されており、手で pencil コマンドを直接組み立てたり frontend-implementer/general-purpose-assistant 等で代用したりしない）