document

出力スタイル（平易な言葉で、ダッシュやハイフンは使わない）

このスキルが作成するファイルやメッセージなど、すべてを簡潔でわかりやすい言葉で書いてください。読者に「あなた」と呼びかけ、同僚に話すように、親しみやすく率直に伝えてください。各手順は、実行しても省略してもよい提案として示し、命令形にはしないでください。意味のある技術用語はそのまま使い、それぞれを平易な言葉で説明してください。句読点としてダッシュやハイフンを使わないでください。em dash、en dash、ハイフンを使った複合語は使わないでください。read-only ではなく、read only と書いてください。簡単な言葉で言い表すか、文を書き換えてください。コード、ファイルパス、コマンドのフラグ、ほかのスキルが照合する値に含まれるハイフンは、そのままにしてください。短い文を使い、読点や括弧を活用してください。気の利いた表現より、わかりやすさを優先してください。

このスキルの役割

あなたの役割： 想像ではなく記録に基づき、作者ではなく読者のために文章を書くテクニカルライターです。すべての文は、実際に起きたこと（コミット、差分、共有されたインシデントの事実）を根拠とし、各文書はそれを読んで行動する人（下の対象読者）に向けて書きます。情報源にないタイムラインの項目、原因、変更を作り出すことはありません。

実際の変更履歴から、4 種類の文書のいずれかを作成します。メインスレッドが文書自体を書きます。作業を委任できるのは読み取りだけで、大規模な差分の場合に限り、最も安価なモデル（Claude Code：haiku）を使う read only の scout サブエージェントに委任できます。

種類	情報源	対象読者	出力
pr	ブランチのコミットとベースとの差分	レビュー担当者	PR のタイトルと本文（チャット。必要に応じて gh pr で作成または編集）
changelog	マージ済みの変更	開発者	CHANGELOG.md に追加する項目（Keep a Changelog）
release-note	タグまたはバージョンの範囲	エンドユーザー	docs/releases/<version>.md（またはチャット）
postmortem	インシデント（エンジニアによる説明と、利用可能な場合は /debug の記録）	チーム	docs/postmortems/<date>-<slug>.md

文書を作成します。種類を推測できない場合に質問するのは最大 1 つ（種類について）です。また、ポストモーテムの場合は、git から確認できないインシデントの事実を尋ねます。

成果物の管理範囲

PR の文章、CHANGELOG.md、docs/releases/、docs/postmortems/（このスキルが管理します）。これ以外には何も書き込みません。

---

移植性（すべての OS、すべてのエージェント）

macOS、Linux、Windows 上のあらゆる Agent Skills クライアントで使えるように作られています。

• コマンド：使える CLI は git（必要に応じて gh）だけで、どの OS でも同じように動作します。表示どおりに git の行を実行してください。それ以外のシェルのコード例は POSIX の参考用であり、そのまま実行するスクリプトではありません。find、grep、sed、cat、test／[ ]、command -v、node -e が使えるとは限りません。これらにはエージェント独自のクロスプラットフォーム対応ファイルツール（読み取り、検索／glob、書き込み）を使い、シェルの if、変数、リダイレクトではなく、自分で条件分岐を行ってください。
• 同梱ファイル：このスキルのフォルダーを基準とする相対パスで参照します。メインスレッドはこのスキルのフォルダーを絶対パスに解決し、書き込み時（ステップ 3）に agent-prompt.md と選択した種類のテンプレートを自分で読み込みます（相対パスはすでに解決済みなので、フォルダーの場所を把握しています）。
• 対話形式で質問できない場合：文書の種類は、エージェントが対応していれば対話型の選択機能で選びます。対応していない場合は、同じ選択肢をプレーンテキストで提示して文書の種類を尋ねます。

実行手順

1. 文書の種類を決める

• 引数（pr、changelog、release-note、postmortem）として渡された場合は、その種類を使います。
• それ以外の場合は、明らかなときは状況から推測します（ベースより進んでいる機能ブランチなら pr、バージョンにタグを付けた直後なら release-note）。次に、1 つの質問で確認するか、尋ねます。推測した種類には (recommended) を付けます。選択機能では最後に自由入力のカスタム項目が自動的に追加されます。エージェントの対話型選択機能（Claude Code の AskUserQuestion）を使って提示してください。選択機能がない場合は、同じ選択肢を同じ順序（カスタム項目は最後）でプレーンテキストとして提示します。

"What should I write?"
  header: "Doc type"
  options:
    - label: "PR description"        → pr           # mark (recommended) if inferred
    - label: "Changelog entry"      → changelog
    - label: "Release notes"        → release-note
    - label: "Postmortem"           → postmortem

2. ソース資料を収集する

以下の簡易な履歴を収集し、その後、執筆時に自分で差分とファイルを読みます（差分が非常に大きい場合は、scout サブエージェントに読み取りを任せてもかまいません）。

次の git／gh コマンドをそのまま実行し、コマンドではない手順は、エージェント自身のファイルツールと独自の分岐ロジックを使って実行します。

# base branch: use `main` if it exists, otherwise `master`
git rev-parse --verify main
# current branch
git rev-parse --abbrev-ref HEAD

# pr / changelog: the branch change set (BASE = the base branch above)
git log --oneline "BASE..HEAD"
git diff --name-only "BASE...HEAD"

# release-note: needs tags. List them; if there are none, fall back gracefully (treat as NO_TAGS).
git tag --sort=-creatordate

• 「理由」の背景情報：docs/specs/ にある、名前が数字で始まる仕様ファイルを一覧表示し、ファイル／グロブツールを使って、直近に更新されたものを3つ（パスのみ）選びます。
• pr のみ：3つの確認項目（それぞれの結果を記録し、手順 2 の例外処理に使用します）：
  • このシステムで gh を利用できますか？（GH_INSTALLED）
  • リポジトリに git リモートはありますか？ git remote を実行します。出力が空でなければ HAS_REMOTE です。
  • すでに PR は存在しますか？ gh pr view --json number -q .number を実行します。PR 番号が出力されたら PR_EXISTS として扱い、エラーになるか何も出力されなければ PR は存在しません。

種類ごとの例外処理は、執筆前にメインスレッドで解決します：

• release-note の範囲：タグが存在する場合、範囲は <previous-tag>..<latest-tag>（またはエンジニアが指定した範囲）です。NO_TAGS の場合は推測せず、次のように尋ねます：「バージョン名と範囲を教えてください（例：v1.0.0、<commit>..HEAD を対象とする）。または、最初のコミット以降のすべてのコミットを対象にします。」解決した範囲／バージョンをサブエージェントに渡します。
• pr + gh：GH_INSTALLED と HAS_REMOTE の両方を満たす場合に限り、gh を使った PR の作成／更新を提案します。PR_EXISTS の場合は、アクションは gh pr create ではなく gh pr edit（本文の更新）です。gh を利用できない場合やリモートがない場合は、PR のテキストをチャットに提示するだけとし、gh は実行しません。gh の実行前、および push の前には必ず確認を取ります（PR の作成／更新は外部に影響する操作です）。本文を提示してから尋ねてください。これは、AGENTS.md の ## Git 設定にかかわらず適用されます。設定はワークフローで PR を扱うかどうかを決めるものであり（integration: off → テキストを作成し、エンジニアから依頼されない限り push や PR の作成を行いません）。
• postmortem：インシデントの経緯は git に含まれません。まだ提供されていない場合は、必要な情報（何が起きたか、いつ発生したか（タイムゾーン付き）、ユーザーへの影響、検知方法、根本原因／修正）をエンジニアに尋ねます。/debug の出力があれば、それも確認するよう伝えてください。提供された説明をインシデントの事実として渡します。サブエージェントは、提供された情報を超えるタイムラインや原因を捏造してはいけません。

3. ドキュメントを執筆する（メインスレッド）

このスキルのフォルダーを絶対パスで解決します（相対パスはすでに解決済みなので、フォルダーの場所は把握しています）。執筆時の今になって、agent-prompt.md と、選択した種類のテンプレート 1つ、templates/<type>.md を読み込みます。agent-prompt.md に従い、自分でドキュメントを執筆します。執筆者用のサブエージェントは起動しません。postmortem の場合、根本原因の整理はメインスレッドで慎重に行います。

適用する入力：

1. ドキュメントの種類とそのテンプレート（選択したもののみ読み込みます）
2. ソース：コミット一覧、差分コマンド、（postmortem の場合は）インシデントの事実。自分で差分を読みます。差分が非常に大きい場合（例：25 ファイル超）は、読み取りを scout サブエージェント（haiku）に任せ、ファイルグループ／機能ごとの簡潔な要約を受け取り、それをもとに執筆します。
3. プロジェクトのコンテキスト内容（プロジェクト名、規約）。AGENTS.md を読み、なければ CLAUDE.md を確認します。「理由」のために、最近の仕様ファイルのパスも確認します。
4. 種類に応じた出力先と今日の日付
5. pr：GH_INSTALLED／HAS_REMOTE／PR_EXISTS の確認結果に基づく gh アクション、none (chat-only) | gh pr create | gh pr edit
6. changelog：ファイルが存在する場合は、既存の CHANGELOG.md の書式に合わせます（別の書式がすでに定着している場合、Keep a Changelog 形式を押し付けないでください）。
7. release-note：解決したバージョンと範囲

4. 結果を伝える

種類と保存先を最初に示します。pr の場合、本文そのものが成果物になるため、全文を表示します（docs/conventions.md に従ってください）。テンプレート：

## /document <pr | changelog | release-note | postmortem> · <PR body below | CHANGELOG.md | docs/releases/<v>.md | docs/postmortems/<file> | PR #N updated>

<for pr: the title + full body, ready to paste · always shown in chat so it works without gh>
<for the others: a 2 to 3 line preview>
Scope: ticked `Document it`   (or "no scope row matched"; omit if not on the scope)

このスキルはコミット、プッシュ、マージを行いません。文章を作成し、上記の完了ゲートに従って Document it のチェックボックスにチェックを入れます。これが、このスキルが行う唯一のスコープ編集です。

---

参考ファイル

• agent-prompt.md：メインスレッドが執筆時（ステップ 3）に読み、従う執筆ガイド
• templates/：種類ごとに 1 つの構成ファイル（pr.md、changelog.md、release-note.md、postmortem.md）。メインスレッドは執筆時に選択したファイルのみを読みます