release-notes

リリースノートスキル

src/ts/docs/help/whatsNew.ts にリリースノートを作成・更新します。このスキルでは、会話のコンテキスト、Git ブランチの変更、または Linear の課題からリリースノートの内容を生成できます。

ドキュメントの構成

src/ts/docs/help/whatsNew.ts は、ブロック要素の配列を返す関数をエクスポートします。各リリースは、次の構成を持つ「ページ」です。

// Helper definitions at top of file (lines 1-24)
const hl = (t: string) => `<span class="highlight">${t}</span>`;
const text = (t: string) => block(I.TextStyle.Paragraph, t);
const h1 = (t: string) => block(I.TextStyle.Header1, t);
const h2 = (t: string) => block(I.TextStyle.Header2, t);
const bullet = (t: string) => block(I.TextStyle.Bulleted, t);
const img = (src: string) => text(`<img src="..." />`);
const link = (url: string, t: string) => `<a href="${url}">${t}</a>`;
const div = () => ({ type: I.BlockType.Div, style: I.DivStyle.Dot });

// Release pages start after helpers (~line 25)
return [
    { type: I.BlockType.IconPage, icon: '...' },

    title(`Catchy Release Title`),           // PAGE START
    h4(`<span>Release 0.XX.0</span>`),
    text(''),
    text('Intro paragraph...'),
    text(''),

    // Big Feature Sections (h2)
    h2(`Feature Name`),
    text(`Feature description...`),
    img(`XX/1.png`),
    text(``),

    // Quality of Life Improvements
    h2(`Quality of Life Improvements`),
    text(``),
    text(`<b>Improvement Name</b>`),
    text(`Description...`),
    text(``),

    // Bug Fixes
    h2(`Bug Fixes`),
    text(``),
    text(`<b>Category Name</b>`),
    bullet(`Fix description. Thanks to @${link('url', 'user')}!`),
    text(``),

    div(),                                   // PAGE END
    // --------------------------------------------//

    // Next release page...
];

複数パートのリリース

リリースは、複数の Linear の親課題（パート）に分割される場合があります。例：

• JS-8571「Release 18 | 0.54.0 | Desktop | Part 1」 — 機能、デザイン、技術を含む
• JS-8672「Release 18 | 0.54.0 | Desktop | Part 2」 — バグ、品質を含む

課題 ID を受け取るコマンド（all、from-parent、docx）は、複数の ID に対応しています。複数の親課題が指定された場合は、それぞれを取得し、子課題をタイプ（機能、QoL、バグ）別に統合します。各パートの項目は Linear での相対的な順序を保ち、パート 1 の項目がパート 2 の項目より前になります。

除外ルール

Linear の課題を処理する際（from-parent、all、docx）、次のいずれかに該当する課題はスキップします。

1. 分析のみ — ラベルに 📈 analytics のみが含まれる（バグ／品質／機能のラベルがない）

2. 内部向け — ラベルに 🖌️ design または ⚙️ tech のみが含まれる（ユーザー向けのラベルがない）

3. アルファ版への言及 — 課題のタイトルまたは説明に、-alpha サフィックス付きのバージョン文字列が含まれる（例：0.53.28-alpha、0.50.29-alpha）。これらの課題はプレリリースビルドに対して報告され、一般公開前にすでに修正されているため、含めると、そのバグを経験していないユーザーを混乱させるおそれがあります。

   検出方法：title または description フィールドで正規表現 \d+\.\d+\.\d+-alpha に一致するものを検索します。

コマンド

ユーザーのコマンドを解析して、実行するアクションを決定します。

/release-notes feature "Title" [context]

現在のリリースに大きな機能を追加します（h2 セクション）。

挿入位置： h2(\Quality of Life Improvements`)` の前

形式：

h2(`Feature Title`),
text(`Description paragraph 1.`),
text(`Description paragraph 2 if needed.`),
text(``),

/release-notes qol "Title" [context]

Quality of Life の改善を追加します。

挿入位置： h2(\Quality of Life Improvements`) の後、h2(`Bug Fixes`)` の前

形式：

text(`<b>Improvement Title</b>`),
text(`Description. Can mention shortcuts like ${hl('Cmd+V')}.`),
text(``),

順序： QoL 項目を複数追加する場合は、影響の大きいものから小さいものの順に並べます。

1. 主要な新機能 — 単独の機能として成立しそうな項目（例：見出しの切り替え、タブの固定、チャットのスペルチェック）
2. 新しい設定と環境設定 — ワークフローを変えるユーザー向けオプション（例：ファイルブロックのデフォルトスタイル、タイトルをクリックして編集する切り替え）
3. 有意義なワークフローの改善 — 使い勝手が明らかに向上する項目（例：コレクションの全文検索、チャット内のメッセージへのジャンプ）
4. 小さいながらもうれしい改善 — 小規模な UX の向上（例：全画面プレビューをクリックして閉じる、ヘッダー内で URL プロパティを開く）
5. QoL と感じられる細かな修正 — ごく小さな品質向上（例：入力欄のクリア、オプションの並べ替え、クリップボード関連の細かな問題）

コミュニティへの謝辞が含まれる項目も、影響に応じてどの段階にも配置できます。別枠にまとめないでください。

/release-notes fix "Category" [context]

指定したカテゴリにバグ修正を追加します。

挿入位置： h2(\Bug Fixes`)` の下で、該当カテゴリを検索するか、新たに作成します。

形式：

text(`<b>Category Name</b>`),  // Only if category doesn't exist
bullet(`Fix description. Thanks to @${link('https://community.anytype.io/t/XXXXX', 'username')}!`),

既存のカテゴリ：

• チャットとメッセージ
• エディターとブロック
• UI とレンダリング
• オブジェクトとビュー
• クエリとビュー
• ウィジェットサイドバー
• ナビゲーションとウィンドウ管理
• キーボードとショートカット
• モーダルウィンドウモード
• その他

/release-notes from-parent JS-XXXX

Linear の親課題とそのサブ課題から、項目を一括作成します。

1. Linear API から親課題とすべてのサブ課題を取得します
2. 各サブ課題のラベルからタイプを判定します。
   • bug ラベル → 修正
   • feature ラベル → 機能
   • improvement ラベル → QoL
3. それぞれに適切な項目を作成します
4. 親課題が大きな機能の場合は、そのタイトルを h2 セクションに使用します

/release-notes new "0.XX.0" "Title"

ファイルの先頭に新しいリリースページを作成します。

挿入位置： IconPage ブロックの後、最初の title() 呼び出しの前

形式：

title(`Catchy Title`),
h4(`<span>Release 0.XX.0</span>`),
text(''),
text('Intro paragraph describing the release highlights.'),
text(''),

h2(`Quality of Life Improvements`),
text(``),

h2(`Bug Fixes`),
text(``),

div(),
// --------------------------------------------//

/release-notes all JS-XXXX [JS-YYYY ...]

1 つ以上のルート Linear Issue（通常はスプリント／マイルストーン Issue）から、完全なリリースノートページを生成します。リリースが複数のパートに分かれている場合は、すべてのルート Issue ID を渡してください。子 Issue は種類ごとに統合されます。

仕組み：

1. Linear API からルート Issue とそのすべての直接の子 Issue を取得します：

curl -s -X POST "https://api.linear.app/graphql" \
  --header "Content-Type: application/json" \
  --header "Authorization: $(printenv LINEAR_API_KEY)" \
  --data '{"query":"query{issue(id:\"JS-XXXX\"){title description labels{nodes{name}}children(first:250){nodes{identifier title description state{name}labels{nodes{name}}children(first:250){nodes{identifier title description state{name}labels{nodes{name}}}}}}}}"}' | jq .

2. 各子 Issue をラベルに基づいて分類します：

子 Issue のラベル	分類	処理
📁 folder + 🐛 bug	バグフォルダー	from-parent と同様に処理します。孫 Issue を取得し、バグ修正のカテゴリに分類して、箇条書きの項目を記述します
📁 folder + 👌 quality	QoL フォルダー	from-parent と同様に処理します。孫 Issue を取得して QoL 項目を記述します。💫 feature ラベルの付いた項目は、代わりに h2 の機能セクションにします
💫 feature（フォルダーなし）	単独の機能	h2 の機能セクションとして記述します
📈 analytics のみ	アナリティクス（内部向け）	完全にスキップします。ユーザー向けではありません

3. リリースページの構成を作成します（まだ存在しない場合）：

   • バージョンとタイトルを含む new ページ
   • すべての h2 機能セクション
   • h2('Quality of Life Improvements') の下にすべての QoL 項目
   • カテゴリ別に整理した、すべてのバグ修正を h2('Bug Fixes') の下に配置
   • intro による導入段落

4. 孫 Issue（フォルダー Issue のサブ Issue）には、同じラベルベースのルールを適用します：

   • 🐛 bug → バグ修正の箇条書き
   • 👌 quality → QoL 項目
   • 💫 feature → 範囲に応じて、h2 の機能セクションまたは QoL 項目
   • 📈 analytics のみ → スキップ
   • 関連するラベルなし → 親フォルダーの種類から推測
   • 👨‍💻 feedback → コミュニティからの報告として扱い、説明からユーザー名とリンクを抽出

5. 実行順序：

   1. 新しいリリースページを作成します（必要な場合）
   2. 機能を挿入します（h2 セクション）
   3. QoL の改善を挿入します
   4. カテゴリ別にバグ修正を挿入します
   5. 導入段落を記述します

コミュニティへの謝辞： サブ Issue に 👨‍💻 feedback ラベルが付いている場合は、説明内のコミュニティへのリンク（https://community.anytype.io/t/XXXXX）を探し、報告者の名前を抽出します。その項目に Thanks to @${link('url', 'name')}! を追加します。

例：

User: /release-notes all JS-8500

Root issue "Sprint 18" has children:
  JS-8574 "Bugs | 18"         [📁 folder, 🐛 bug]     → process 81 bug sub-issues
  JS-8573 "Quality | 18"      [📁 folder, 👌 quality]  → process 25 QoL sub-issues
  JS-292  "[epic] Tabs"        [💫 feature]             → h2 feature
  JS-4551 "[epic] Filters"    [💫 feature]             → h2 feature
  JS-8725 "Chat Search"       [💫 feature]             → h2 feature
  JS-8703 "Transfer Ownership" [💫 feature]            → h2 feature

Result: Complete release page with features, QoL, bug fixes, and intro.

/release-notes docx JS-XXXX [JS-YYYY ...]

現在のリリースノートを、Linear の課題へのハイパーリンク付き .docx ファイルとしてエクスポートします。項目は、カテゴリ別にグループ化した whatsNew.ts の順序ではなく、Linear の並び順（親課題の下に表示される子課題の順序）に従います。

1 つ以上のルート課題 ID を指定できます。リリースが複数の Linear 課題（「パート」）に分割されている場合は、すべての課題を指定してください。各課題の子課題は種類別（機能、QoL、バグ）にまとめられ、各パートの項目は統合後のセクション内でも元の順序を保ちます。

動作の仕組み：

1. Linear から各ルート課題と、そのすべての子課題ツリーを取得します（first:250 を使用します）。

curl -s -X POST "https://api.linear.app/graphql" \
  --header "Content-Type: application/json" \
  --header "Authorization: $(printenv LINEAR_API_KEY)" \
  --data '{"query":"query{issue(id:\"JS-XXXX\"){title description labels{nodes{name}}children(first:250){nodes{identifier title description state{name}labels{nodes{name}}children(first:250){nodes{identifier title description state{name}labels{nodes{name}}}}}}}}"}' | jq .

2. 次のルールに従って、すべてのルート課題から子課題を収集し、分類します。

子課題のラベル	分類	処理
💫 feature（📁 folder の有無は問いません）	機能	フォルダーの場合：孫課題を個別の機能として扱います。単独の場合：1 つの機能項目として扱います
📁 folder + 👌 quality	QoL フォルダー	孫課題を QoL 項目として扱います。💫 feature ラベルの付いた項目は機能として扱います
🐛 bug（📁 folder の有無は問いません）	バグフォルダー	孫課題をバグ修正として扱います
📈 analytics のみ	アナリティクス	スキップ
🖌️ design / ⚙️ tech のみ	内部向け	スキップ — ユーザー向けではありません

パート間で統合する場合、各セクション内ではパート 1 の項目の後にパート 2 の項目を追加します（各パート内の順序は維持します）。

3. whatsNew.ts から現在のリリースページを読み込み、各項目に対応するユーザー向けのノート本文を取得します。

4. 各 Linear の課題を whatsNew.ts の項目に対応付けます。対応付けの方法は次のとおりです。

   • 機能の場合：h2 のタイトルに含まれるキーワードで対応付けます（例：JS-292「Tabs」→ h2(\Tabs`)`）
   • QoL 項目の場合：太字のタイトルに含まれるキーワードで対応付け（例：「Toggle Headings」→ text(\Toggle Headings`)`）し、その後に続く説明の段落を取得します
   • バグ修正の場合：コミュニティリンクの URL（community.anytype.io/t/XXXXX）、課題のタイトルに含まれるキーワード、または同じカテゴリ内での位置で対応付けます
   • 対応する項目が見つからない場合は、Linear の課題タイトルを代替テキストとして使用し、**Title** – <Linear title>. の形式にします。

5. 次の構造の JSON データファイルを作成し、各セクション内ではLinear の子課題の順序を維持します。

{
    "version": "0.54.0",
    "title": "Focus & Flow",
    "sections": [
        {
            "heading": "Features",
            "items": [
                {"id": "JS-292", "text": "Note text from whatsNew.ts (cleaned of HTML)."},
                {"id": "JS-4551", "text": "..."}
            ]
        },
        {
            "heading": "Quality of Life Improvements",
            "items": [
                {"id": "JS-XXXX", "text": "**Toggle Headings** – H1, H2, H3 can now be collapsible toggles..."}
            ]
        },
        {
            "heading": "Bug Fixes",
            "items": [
                {"id": "JS-8845", "text": "Action icons now look consistent across light and dark modes."}
            ]
        }
    ]
}

6. whatsNew.ts からテキストを抽出する際の整形ルール：

   • HTML タグを削除します：<span class="highlight">X</span> → X、<b>X</b> → **X**、<i>X</i> → X
   • <a href="...">text</a> → text に変換します
   • テンプレート式を解決します：${hl('Cmd+F')} → Cmd+F、${link('url', 'name')} → name
   • QoL 項目では、太字のタイトルと説明の段落を結合し、1 つのテキスト文字列にします：**Title** – Description text.
   • 機能では、すべてのテキスト段落を結合して 1 つの文字列にします

7. JSON を一時ファイルに書き込み、ジェネレータースクリプトを実行します。

python3 .claude/skills/release-notes/generate_docx.py /tmp/release_data.json <output_path>

出力先： プロジェクトのルートに release-<version>.docx として .docx を保存します（例：release-0.54.0.docx）。

項目の順序： 各セクション内の項目は、Linear の親課題の下に表示される順序と必ず同じにしてください。この順序は、Linear API の children フィールドから返される順序です。カテゴリ、アルファベット順、その他の基準で並べ替えてはいけません。複数のパートを統合する場合は、パート 1 の項目を先に、その後にパート 2 の項目を配置します。

例（複数パート）：

User: /release-notes docx JS-8571 JS-8672

1. Fetch JS-8571 (Part 1) children:
   - JS-8575 [💫 + 📁] → Features folder → 4 feature grandchildren
   - JS-8630 [🖌️ + 📁] → Design folder → skip (internal)
   - JS-8594 [⚙️ + 📁] → Tech folder → skip (internal)

2. Fetch JS-8672 (Part 2) children:
   - JS-8573 [👌 + 📁] → QoL folder → 33 grandchildren → QoL items
   - JS-8574 [🐛]       → Bug folder → 82 grandchildren → Bug Fixes

3. Merge: Features from Part 1, QoL from Part 2, Bugs from Part 2
4. Read whatsNew.ts, match each issue to its note text
5. Write JSON with items in Linear order
6. Run generate_docx.py → release-0.54.0.docx
7. Report: "Generated release-0.54.0.docx with 4 features, 33 QoL items, 82 bug fixes."

/release-notes intro

現在のリリースの導入段落を作成または更新します。

動作の仕組み：

1. whatsNew.ts から現在のリリースページを読み込みます
2. すべての h2 機能セクションを特定します
3. 主な機能の要点を強調する 2～3 文を書きます
4. h4(...) と最初の h2(...) の間にある空の導入文 text('') を置き換えます

挿入位置： h4(<span>Release ...</span>) と最初のコンテンツセクションの間にある text('') の行

形式：

text('Intro sentence one. Intro sentence two.'),
text('Intro sentence three if needed.'),

スタイル：

• 簡潔で意欲的な 2～3 文にします。ただし、大げさになりすぎないようにします
• 主な機能を名前で挙げます
• 実装の詳細ではなく、ユーザーができるようになったことに焦点を当てます
• ファイル内の過去のリリース導入文のトーンに合わせます

/release-notes show

現在のリリースノートを表示します（ファイルの先頭ページ）。

コンテキストの解決

ユーザーが明示的なテキストの代わりにコンテキストのヒントを提示した場合：

today または session

1. 現在の会話履歴を分析します
2. 話し合われた、または実装された機能や変更を特定します
3. ユーザーにとっての主なメリットを抽出します
4. リリースノートの形式で説明を作成します

branch

1. git log main..HEAD --oneline を実行してコミットを確認します
2. git diff main --stat を実行して変更されたファイルを確認します
3. ブランチ名からコンテキストを分析します（例：feature/JS-8826-advanced-filters）
4. 変更内容に基づいて説明を作成します

JS-XXXX（Linear の課題）

1. 次を使用して Linear API から課題を取得します：

curl -s -X POST "https://api.linear.app/graphql" \
  --header "Content-Type: application/json" \
  --header "Authorization: $(printenv LINEAR_API_KEY)" \
  --data '{"query":"query{issue(id:\"JS-XXXX\"){title description state{name}priority labels{nodes{name}}}}"}' | jq .

2. タイトルと説明を抽出します
3. カテゴリが指定されていない場合は、ラベルを使って判断します
4. リリースノート向けに整形します

明示的なテキスト

提示されたテキストをそのまま使用しますが、スタイルガイドラインに従っていることを確認します。

執筆スタイルのガイドライン

トーン

• 簡潔でありながら、情報を十分に伝えます
• 何が変わったのか、そしてそれがユーザーにとってなぜ重要なのかを説明します
• 能動態を使います：「これで〜できるようになりました」ではなく、「〜することが可能になりました」のような受動的な表現は避けます
• 実装の詳細ではなく、ユーザーにとってのメリットに焦点を当てます

機能のタイトル

行動を促す、分かりやすい名前にします：

• 「ダイレクトチャンネル」
• 「高度なフィルター」
• 「クエリの手動並べ替え」
• 「ナビゲーションの更新」

説明

• ユーザーのメリット、または解決した問題から書き始めます
• キーボードショートカットは ${hl('Cmd+V')} の形式で記載します
• 段落では1つの考えに絞ります
• テキスト内で強調するには <b>太字</b> を使います

コミュニティへの謝辞

ユーザーから報告された問題を修正した場合：

bullet(`Fix description. Thanks to @${link('https://community.anytype.io/t/12345', 'username')}!`)

句読点

• 挿入句や範囲には、em ダッシュ（—）ではなく en ダッシュ（–）を使います

避けること

• 技術用語（API、リファクタリング、コンポーネント名）
• 実装の詳細（ファイル名、関数名）
• 受動態
• 曖昧な説明（「パフォーマンスを改善しました」）

ワークフロー

1. コマンドを解析 - アクションの種類と引数を特定します
2. コンテキストを解決 - 会話、ブランチ、Linear、明示的なテキストから内容を作成します
3. whatsNew.ts を読む - 現在のリリースと挿入位置を確認します
4. エントリーを整形 - 適切な TypeScript の構文とスタイルを適用します
5. エントリーを挿入 - 正しい位置にファイルを編集します
6. 確認 - 追加した内容をユーザーに提示します

例

セッションのコンテキストから機能を追加する

User: /release-notes feature "Advanced Filters" today

Action:
1. Review conversation - user worked on advanced filters with AND/OR logic
2. Find insertion point before h2(`Quality of Life Improvements`)
3. Insert:
   h2(`Advanced Filters`),
   text(`Need more control over what shows in your Views? You can now create Advanced Filters that combine multiple conditions using AND or OR logic. Group related rules together to build precise queries – like finding all tasks that are either high priority or due this week.`),
   text(``),

QoL の改善を追加する

User: /release-notes qol "Filter Bar Redesign" branch

Action:
1. Analyze git changes on current branch
2. Find insertion point after h2(`Quality of Life Improvements`)
3. Insert:
   text(`<b>Filter Bar Redesign</b>`),
   text(`Filters and Sorts in Queries and Collections got a fresh look. Active filters now appear in a dedicated bar above your View, showing the property name, condition, and value at a glance.`),
   text(``),

バグ修正を追加する

User: /release-notes fix "Objects & Views" "Filter items now show correct active state"

Action:
1. Find h2(`Bug Fixes`)
2. Find text(`<b>Objects & Views</b>`) category (or create if missing)
3. Insert bullet after category header:
   bullet(`Filter items now show correct active state.`),

リリースの導入文を書く

User: /release-notes intro

Action:
1. Read whatsNew.ts — find h2 feature sections: "Tabs", "Advanced Filters", "Chat Search", "Transfer Channel Ownership"
2. Write 2–3 sentences covering the highlights
3. Replace empty text('') lines after h4(`<span>Release 0.54.0</span>`):
   text('This release brings Tabs to Anytype — open multiple Objects side by side and pin the ones you use most. Advanced Filters let you combine conditions with AND/OR logic, Chat Search helps you find any message instantly, and Channel Owners can now transfer ownership to another member.'),

ルート課題からすべてのリリースノートを作成する

User: /release-notes all JS-8500

Action:
1. Fetch root issue JS-8500 — "Sprint 18" with 6 children
2. Classify children:
   - JS-8574 [📁 + 🐛] → bug folder, fetch 81 grandchildren → bug fixes
   - JS-8573 [📁 + 👌] → QoL folder, fetch 28 grandchildren → QoL entries + features
   - JS-292  [💫]       → standalone feature "Tabs"
   - JS-4551 [💫]       → standalone feature "Advanced Filters"
   - JS-8725 [💫]       → standalone feature "Chat Search"
   - JS-8703 [💫]       → standalone feature "Transfer Ownership"
3. Create new release page with `new "0.54.0" "Focus & Flow"`
4. Insert 4 feature h2 sections
5. Insert 25 QoL entries
6. Insert 80 bug fixes across categories
7. Write intro paragraph