management-talk

マネジメント向けの説明

書面の進捗報告と同じ対象者向けですが、投稿先に合わせた形にします。JIRA のコメント、Slack の投稿、非同期のスタンドアップ、メール、会議用の要点などが該当します。読者はコード名には詳しいものの、コードそのものは読みません。長さ、書式、どの程度の構成を残すかは投稿先に合わせます。

エンジニアリングの情報を組織の上層部に伝える場合、プロダクトやリリース担当に共有する場合、またはエンジニアリング以外のメンバーが参加する会議で話す場合は、投稿先にかかわらず、いつでもこれを使ってください。

使うタイミング

• 「マネジメント／経営幹部／VP／ディレクター／PM／リリースマネージャー向けに何か書いて」
• 「これを［エンジニアリング以外の対象者］向けに書き直して」
• 「技術的でない表現にして」／「技術用語を減らして」／「専門用語を減らして」
• 「エンジニアリングの作業について」Slack の進捗報告／スタンドアップのメモ／メールを送って
• 「エグゼクティブサマリー」／「経営幹部向けサマリー」／「リーダーシップ向けの報告」／「進捗報告」
• 「エンジニアリングの進捗報告をもとに」［会議］向けの要点をまとめて

きっかけとなる依頼のあとも投稿先が不明な場合は、短く質問を1つだけして、そこで止めてください。「JIRA、Slack、スタンドアップ、メールのどれですか？」

対象者 — 「エンジニアリング組織のリーダー層」とは

エンジニアリングに詳しい非エンジニアです。VP、ディレクター、PM、リリースマネージャー、技術製品を出荷する企業の経営幹部などが該当します。プロダクト名やフレームワーク名を読み、JIRA の課題キーや PR を相互参照します。コードは読みません。

知りたいのは、現状はどうか、顧客にとってどんな意味があるか、担当者は誰か、次に何をするかです。関数レベルでバグがどう動くかは求めていません。

これは、マーケティング、財務、顧客向け、または本当に子ども向けの説明が必要な対象者向けではありません。その場合は別の書き換えが必要です。作成する前に、その旨を伝えて確認してください。

トーン

残すもの。 プロダクト名、フレームワーク名、チームが管理するコンポーネント名、JIRA の課題キー、PR 番号、顧客やワークロードの識別子（Tada、DeepSpeed、PyTorch、Llama-2-70B、vLLM、JIRA-12345、PR #5751）。これらは、エンジニアリングとリーダー層の追跡管理をつなぐものです。

省くもの。 関数名、ファイルパス、構造体のフィールド、コミット SHA、コード式、環境変数名、行番号、内部データ構造の専門用語（tadaLaunchPrepare、tada/prim.h::syncWaitPeer、scratchBuf、0e0a6bac）。対象者にとって、これらから実行可能な対応は導き出せません。

言い換えるもの。 仕組みを、原因と結果がわかる平易な文章1、2文にします。*「カーネルが scratchBuf == NULL から読み込む」ではなく、「GPU が未初期化のバッファーから読み込み、届かないシグナルをいつまでも待ち続けます」*とします。事実を曲げずに言い換えてください。競合状態は競合状態のまま、リグレッションはリグレッションのままです。

省きすぎないでください。 エンジニアリング組織のリーダー層は、概念レベルの技術用語をよく理解しています。競合状態、同期、未初期化バッファー、ファストパス、回避策、登録、キュー、ドライバー、カーネル（GPU の意味で）などです。基準となるのは、ここに存在し重要な概念か（残す）、それとも関数、構造体、ファイル、SHA の詳細か（省く）です。「競合状態」を「タイミングの問題」と言い換えるのは、読者を見くびる表現です。

意識すること。 能動態、具体的な主語、短い段落を使います。*「バグを見つけました。Alex が修正を書きました。PR をレビューに出しています。」のほうが、「根本原因が特定され、修正が作成されてレビューに提出されました。」*よりも適切です。

避けること。

• 実質的な留保になっていない曖昧な表現（「そう考えています」「そのようです」「可能性があります」）。断言するか、触れないかのどちらかにしてください。
• 念を入れるために、明らかなことを言い直す表現（「このバグは Tada にあり、Tada は GPU 通信に使われていて、GPU 通信は分散トレーニングに重要で、その分散トレーニングは……」）。
• リーダー層に仕事の進め方を指示する表現（「優先すべきです」「X より前に取り込む必要があります」）。事実を伝え、判断は相手に委ねてください。
• エンジニアリングのプロセスの細部。二分探索の実行、デバッグの反復、GDB セッションなどです。重要なのは問題を見つけたことであり、その方法ではありません。（例外：プロセス自体が伝えるべき内容の場合。「二分探索が誤解を招くと気づくまでに3週間を費やしました」など。その場合は、手順を逐一説明せず、学びとして1文で述べます。）

投稿先に合わせた形式

内容は同じでも、形式は変わります。投稿先に合った形を選んでください。

JIRA コメント／状況報告書

完全な構成のブロックです。セクションラベルは太字にします。チケットページから簡単に把握できます。

組み立て要素（必要に応じて使用してください）：

• 状況／要約。 太字の1行です。これだけ読めば、読者は正しい状況を把握できます。"マージ待ちの修正済みです。"／"根本原因は不明です。調査中です。"／"ベンダーの対応待ちです。"／"7.2で顧客に影響するリグレッションが発生しており、ロールバック中です。"
• 影響。 誰に、どの程度の影響があり、何が起きているかを記します。テストスイートの用語ではなく、顧客／ワークロード／製品の用語を使います。"Llama-2-70Bのファインチューニングがすべての評価ステップで停止する" ＞ "テストが失敗する。"
• 何が壊れたか。 短い段落で記します。仕組みを平易な言葉で説明し、原因は1段階までにとどめ、コード識別子は使いません。
• なぜ今か／どうして見逃されたか。 任意です。いずれにせよ経営陣から質問される場合に含めます。潜在的なリグレッション、CIの抜け、以前の不完全な修正、凍結期間中に入った変更などです。
• 担当者。 担当者＋チーム＋その人のPR／ブランチ／JIRAの成果物を記します。リンクは5つではなく1つにします。
• 次の手順。 具体的で、直近のものを順に記します。"コードレビュー → マージ → 7.2にバックポート。"
• 回避策／緩和策。 顧客が現在この問題に直面している場合、今日できることを1文で記します。
• リスク。 任意です。実際にあるリスクだけを記します。"修正はホットパスに影響するため、ベンチマークを実施するまではパフォーマンスのリグレッションが起きる可能性があります。" 十分な説明に見せるために、リスクをでっち上げないでください。

この項目にとって最も重要なものから順に並べます。

Slack — チャンネル投稿またはDM

メッセージは1つにし、長文の壁を作らないでください。セクションラベルをたくさん太字にすると、「JIRAから逃げてきました」という印象になるので避けます。

• 最初の行を太字の要約にします。
• その下に、影響、担当者＋リンク、次の手順を2～4個の短い箇条書きで示します。該当しないブロックは省きます。
• リンクはインラインで埋め込んだものを1つだけにします（JIRA-12345／PR #5751）。リンクだらけにしないでください。
• 挨拶も結びの言葉も不要です。チャンネルが文脈になります。
• 新規投稿ではなくスレッドへの返信の場合は、要約を省いて、回答から始めます。

長さの目安：トップレベルの投稿は約80語未満、スレッドへの返信は約40語未満です。

非同期のスタンドアップメモ

読者は30秒でメモを10件読みます。動詞を先頭に置きます。

• 最大1～3行です。
• パターン：「<状態> <対象>。<自分以外の担当者がいれば記載>。<次の手順>。」
• 例：
  • 「dumbModelの実行に影響するTadaの停止を修正しました（JIRA-12345）。PR #5751はレビュー中です。次にv7.2へバックポートします。」
  • 「LLM-7Bの評価ステップの停止を引き続き調査中です。再現手順は安定しました。現在、二分探索で原因を絞り込んでいます。現時点で完了予定はありません。」
• 箇条書きも太字のラベルも使いません。文そのものがフォーマットです。

メール — 社内の経営陣／チーム間

件名が価値の半分を占めます。

• 件名： 要約を名詞句に書き換えます。"dumbModelでのTadaの停止：修正をレビュー中（JIRA-12345）。"
• 挨拶： 受信者に合わせます（Hi Sam,／Hi all,）。
• 本文： JIRAコメントの形式を使いますが、太字のセクションラベルではなく、空行で区切った流れるような段落にします。2～3段落で十分です。
• 結び： 受信者に注意を促す必要がある次の判断事項があれば、それを記します。なければ、簡潔に "— [Name]" とします。

会議での発言メモ

これは見せるものではなく、話すためのものです。

• 箇条書きにし、各項目は短い節1つまでにします。
• 話す順番に並べます。
• 口頭で参照したい数値やキーは、言いよどまないよう箇条書きの中に含めます。
• 説明文は省きます。"dumbModelのLLM-7Bファインチューニングが停止していました。"／"根本原因：Tadaの高速パスで同期がスキップされていました。"／"Alexの修正はレビュー中です。PR #5751。"／"マージされたらv7.2にバックポートします。"

ソース資料

入力は次のいずれかです。

1. JIRA チケットキー（例：JIRA-12345）→ GET /rest/api/3/issue/<KEY>?fields=summary,status,priority,assignee,comment と、技術評価に使用するインスタンス固有のカスタムフィールド（通常はこれが最新状況を把握する最も確実な情報源です）を取得します。書き換えるのは、内容のある最新のコメントです。スレッド全体をそのまま出力しないでください。
2. 貼り付けられた技術テキスト → そのまま使用します。
3. 現在の会話 → あなた（またはユーザー）が直前にエンジニアリング関連の内容を作成し、ユーザーが「今度は Slack 向けに」／「今度は VP 向けに」と言った場合は、会話の内容を再利用します。

ソースが曖昧な場合は、質問を1つだけして終了します。

出力の流れ

1. 指定がなければ、チャネルを確認します。
2. 下書きを作成します。 チャネル上での表示形式に合わせ、チャットブロック1つにまとめます。
3. 投稿先を尋ねます。
   • デフォルト：表示のみ。ユーザーがコピーします。
   • JIRA へのコメント投稿：ユーザーが明示的に指示した場合のみ行います。正確な ADF ペイロードを提示し、明示的な「投稿して」／「進めて」／「はい」を待ってから、POST /rest/api/3/issue/<KEY>/comment を実行します。
   • このスキルでは、Slack、メール、その他 JIRA 以外のチャネルには絶対に投稿しません。 下書きをユーザーに渡し、投稿はユーザー自身に行ってもらいます。
4. 通常は1回の修正で十分です。3回目の修正は要注意です。 ユーザーが3回目の修正を求めた場合は、やみくもに調整を続けず、どのような表現や対象読者に関する前提が不足しているのか、具体的に尋ねます。

例 — 同じバグを3つのチャネル向けに作成

ソース（エンジニアリング関連の JIRA コメント）：

仕組み： tadaLaunchPrepare / tadaLaunchKernel / tadaLaunchFinish の単一ストリーム高速パス（scheduler->numStreams == 1 && !plan->persistent を条件として有効化）で、launchStream と handle->shared->deviceStream の間のクロスストリームイベントがスキップされていました。dumbModel はこの条件に該当します。deviceStream による IPC 公開／スクラッチバッファへの書き込み（scratchBuf を設定する処理）が launchStream から見えるようになる前にカーネルが起動されていました → カーネル内で scratchBuf == NULL → 不正なポインター参照 → リングの ready フラグを不正な値から読み取り → スレッドが永久にスピンします。

JIRA コメントとして

状況：修正済み、マージ待ちです。 バグを発見し、修正を検証済みです。PR はレビュー待ちです。

影響： 8 GPU での LLM-7B ファインチューニングでは、モデルの評価を試みるたびにハングし、ワークロード全体が停止していました。dumbModel（単一 GPU に収まらない大規模モデルのトレーニングで広く使われているフレームワーク）の利用者に影響するため、このプラットフォームでの大規模モデルのファインチューニング実行の大半が影響を受ける可能性がありました。

問題の内容： GPU 通信ライブラリ（Tada）が、dumbModel が起動する特定の構成で内部同期処理をスキップしていました。その結果、GPU が初期化されていないバッファーを読み取り、決して届かないシグナルを待ち続けていました。この危険なショートカットは数か月前からコードに存在していましたが、実際のワークロードで到達したのは今回が初めてです。

以前の修正の試みでは、特定の経路で症状を隠す防御的なチェックが追加されましたが、根本的な競合状態は残っていました。今回の修正では、危険なショートカットを完全に削除し、デバイス側の安全性チェックを強化します。

担当者： Alex（Tada チーム）。PR org/platform#5751。

次のステップ： コードレビュー → マージ。現在この問題が発生しているお客様は、一時的な回避策として IPC 登録を無効にできます。

Slack 投稿として

dumbModel の LLM-7B ファインチューニングに影響する Tada のハングを修正済み、マージ待ちです。（JIRA-12345）

• 通信の高速パスで同期がスキップされていた → GPU が初期化されていないメモリーを読み取り → ハング。数か月間潜在していましたが、この問題に遭遇したのは dumbModel が初めてです。
• 担当者：Alex。PR #5751 はレビュー中です。
• マージまでの回避策：IPC 登録を無効にします。

スタンドアップ用メモ

dumbModel LLM-7B で発生していた Tada のハングを修正しました（JIRA-12345）。Alex の PR #5751 はレビュー中です。回避策はチケットに投稿済みです。次は v7.2 へのバックポートです。

チャネル間で変わったのは、診断、担当者、次のステップは同じという点です。JIRA にはすべての情報を記載します。Slack では「今なぜ対応するのか」と「以前の修正の試み」は省きます。チャネルには情報が多すぎるためです。スタンドアップでは、状態、キー、担当者、次のステップだけを残します。どのチャネルにも scratchBuf や tadaLaunchPrepare には言及していません。

ルール

• 内容を整えるために事実を捏造しないでください。 エンジニアリングの情報源に「根本原因は不明」とあれば、書き換え後も「根本原因は不明」とします。文章を整えるために、推測を確定事項として扱ってはいけません。
• 専門用語をわかりやすくする際に、JIRA キー、PR 番号、顧客名／ワークロード名を絶対に削除しないでください。 これらは相互参照の要であり、失うと追跡できなくなります。
• 担当者を捏造しないでください。 情報源に担当者の名前がない場合は、git blame や最近のコミットから推測せず、ユーザーに確認してください。
• JIRA に投稿する前に承認を得てください。 jira-check の承認フローを再利用してください。印刷のみの出力には承認は不要です。
• このスキルから、Slack、メール、または JIRA 以外のチャネルに投稿しないでください。 下書きをユーザーに渡し、投稿はユーザーに行ってもらいます。
• 意見の主張は避けてください。 このスキルが作成するのは状況報告であり、提案ではありません。ユーザーが提案メモを希望する場合は、書き換える前に確認してください。