work-report

name	work-report
description	完了した作業を tmp の Markdown レポートに書き出して報告する skill。レポートは簡潔（短い1行ずつ・jargon なし）に保ちつつ、example code・before/after diff・mermaid 図は使えるときは多めに入れ、TUI には1行サマリと file path だけ出す。明示的に呼ばれた時に加え、作業・タスク・調査・修正・コミット等が一区切りついて「何をやったか」を伝える場面では毎回この skill を使う（ユーザーがざっくり説明を頼まなくても自動で）。長い作業サマリを TUI に直接書く代わりに、必ずこの形式で tmp MD に書き出すこと。

work-report

作業が一区切りついたら、その内容を tmp の Markdown レポートに書き出して報告する。TUI には1行サマリと path だけ出す。レポートは簡潔（短い1行ずつ・jargon なし）に保ちつつ、example code・before/after・mermaid 図は使えるときは多めに入れる。

なぜ

• 作業サマリを TUI に長文で書くと読み負担が大きい。判断や次の行動に要らない文脈が紛れる。
• でも「何をやったか」は文章より図・コード差分で見た方が速い。
• だから本文は tmp MD に逃がし、そこは図/コードでリッチにする。TUI は1行サマリ + path に絞る。

いつ使う

• 明示的に呼ばれた時。
• 作業・タスク・調査・修正・コミット等が一区切りついて「何をやったか」を伝える時は毎回（頼まれなくても）。

フロー

1. レポートを $TMPDIR/work-report-<slug>.md に書く（<slug> = 作業内容の短い kebab-case）。
2. TUI には1行サマリ + path だけ出す。長文・多階層 list・大きい表は TUI に書かない。

TUI 側の例:

core/offline の publishConfig.exports 追加、検証 green。詳細: /tmp/work-report-publish-exports.md

レポートの形

固定の重いテンプレではなく、必要なセクションだけ使う。各セクションは「使えるとき」図/コードを多めに。

# <作業タイトル>

## 背景（何の話か）

<この作業が何の一部で、なぜ必要かを、読み手が文脈ゼロでも掴めるよう平易に 2-4 行。jargon は避けるか、ここで噛み砕いてから使う。ここが薄いと「何いってるか分からん」レポートになる>

## やったこと

- <1 行ずつ。変更点を端的に>

## 中身

<before → after / diff / コード例。構造・流れが絡むなら mermaid 図>

## 検証

- <test / 動作確認の状況。green でも red でも正直に 1 行>

## 残り

- <あれば 1 行ずつ。無ければセクションごと省略>

書き方

• まず前提を立てる。 読み手は文脈を持っていない前提で書く。冒頭の「背景」で「何の話か・なぜやるか」を平易に示してから詳細に入る。jargon を前提にせず、使うなら背景で噛み砕く。これが最優先。
• 1 行ずつ・jargon なし。 前置きの長段落を書かない。1 文に畳む。
• 図/コードは多めに。 文章で説明するより見せる。
  • 変更前後 → コードブロックで before / after か diff
  • 流れ・関係・構造・依存 → mermaid（flowchart / sequenceDiagram / graph / stateDiagram-v2 等）
  • 数値・内訳 → 小さい表か pie
• 盛らない。 当てはまらないセクションは省く。1 つの小さな変更に図を無理に付けない。図/コードは「あった方が速いとき」だけ。
• 言語は相手に合わせる（このユーザーは日本語タメ口が基本）。

mermaid を使うなら

• ラベル内の半角 () は全角 （） に置換する。半角は shape 構文と衝突して図全体が壊れる。
• node ID に予約語（graph / end / state 等）を使わない。
• stateDiagram-v2 は 1 行 1 遷移（A --> B --> C を 1 行に書かない）。
• 詳細な落とし穴は explain-with-diagrams skill を参照。

OK / NG

OK:

publishConfig.exports を全パッケージに追加、tgz 検証 green。詳細: /tmp/work-report-publish-exports.md

NG（TUI に長文サマリを直接書く）:

publishConfig.exports を core と offline に追加しました。これは dev では src を
指したまま、公開時だけ dist の .d.mts を指すようにする変更で、理由は files が
dist しか含まないため… [段落が続く]

→ この本文は tmp MD に書き、TUI は 1 行 + path にする。

起動

• 作業の区切り・タスク完了・調査完了・修正完了・コミット後など「何をやったか」を報告する任意の場面で自動適用。
• ユーザーが明示的に呼んだ時も同じ形式で出す。