prospective-release-notes

リリースノートの作成候補

期間の両端となるブランチを2つ選び、リリースノートのSOPに引き継ぎます。アンカーの選定対象はアプリケーションのデフォルトアプリケーショングループに限定されます。Service Pack のホットフィックスグループは明示的に除外されるため、週の途中のホットフィックスによって比較結果が左右されることはありません。

実行時の方針

このスキルは、非対話型環境でスケジュールに従って無人実行されるように設計されています。実行中に確認を求められる呼び出し元はいません。曖昧さや入力不足、ツールエラーに遭遇した場合、すべてのステップで、エージェントの出力に明確で自己説明的なメッセージを表示して失敗する必要があります。オペレーターは後からスケジューラーのログを確認し、入力を修正して再実行します。

推測しないでください。「最初の一致」を選ばないでください。明確にエラーを通知してください。

対話的に呼び出された場合（ユーザーが「 の週間リリースノート」と入力した場合）も、曖昧さに対しては同じ方針が適用されます。ただし、目の前のユーザーがオペレーターとなるため、エラーを表示して曖昧な点を明確にするよう求めてください。

依存関係

• release-notes-generator スキル — ステップ3で両方のアンカーの存在が確認できたら、解決済みの2つのブランチIDを渡して呼び出します。

前提条件

• 組織名とアプリケーション定義名 — どちらも必須です。アプリケーション名は組織内でのみ一意のため、組織名が明らかな場合でも省略できません。
• 期間： range_start（開始を含む）と range_end（終了を含む）。指定がない場合は、ユーザーのローカルタイムゾーンで先週の月曜日 00:00 → 先週の日曜日 23:59:59がデフォルトになります。

公開済みリリースはDatex Studioマーケットプレイスにあります。これらのリリースはデプロイ先に依存しません。「公開済み」とは、どの環境でも利用できることを意味し、いずれかの環境で現在そのバージョンが稼働しているという意味ではありません。このスキルはマーケットプレイスのメタデータを読み取るため、デプロイ先は必要ありません。

ワークフロー

[Step 1: Resolve org / repo / defaultApplicationGroup]
dxs --output json organization search "<ORG_NAME>"
  → <ORG_ID> (fail hard on 0 or >1 match)
dxs --output json organization app list --org <ORG_ID>
  → find entry where name == <APP_NAME>
  → <REPO_ID>, <defaultApplicationGroupId>
  (fail hard on 0 matches)
        |
[Step 2: Collect release branches in the Default group]
dxs --output json source branch list \
  --repo <REPO_ID> --default-group --status published -n 0
        |
[Step 3: Pick the two anchors]
Sort filtered releases by releaseDate descending.
  last_before   = largest releaseDate strictly less than range_start
  last_in_range = largest releaseDate in [range_start, range_end]
        |
        +--- Outcome 1: no last_in_range     → emit "No releases …" and stop
        |
        +--- Outcome 2: last_in_range but no last_before
                                             → emit Initial Release note and stop
        |
        +--- Outcome 3: both exist           → Step 4
        |
[Step 4: Delegate]
Invoke release-notes-generator with --from=<last_before.id> --to=<last_in_range.id>
(Use `dxs source release-notes --enrich-workitems --output json` as the source call
 if the target skill wants structured data; otherwise pass the branch IDs and let
 release-notes-generator drive its own workflow.)
        |
[Step 5: Return]
Return the Technical + Customer notes as the agent's response. No persistence
to KB / file / chat — the caller decides downstream delivery.

ステップの詳細

ステップ1：(orgId, repoId, defaultApplicationGroupId) を解決する

# 1a. Organization name → organization ID
dxs --output json organization search "<ORG_NAME>"

# 1b. Apps in that org
dxs --output json organization app list --org <ORG_ID>

アプリ一覧から、name == <APP_NAME> に該当するエントリを選び、その id（= <REPO_ID>）と defaultApplicationGroupId を取得します。

即時失敗の条件（推測したり、最初の一致を選んだりしないでください）：

• 入力（組織名またはアプリケーション名）のいずれかが不足している。
• 組織の検索結果が0件、または複数件である。
• 組織内でのアプリ検索結果が0件である。

各エラーメッセージには、検索対象、検索結果、修正のために呼び出し元が指定すべき内容を含める必要があります。例：

「'Datex' の組織検索で3件が見つかりました：[1 Datex、47 Datex Demo、 88 Datex Partners]。組織名をより具体的に指定するか、組織IDを直接渡して再実行してください。」

ステップ1の終了時に取得している必要があるもの： <REPO_ID>（ステップ2で --repo として使用）と <defaultApplicationGroupId>（ステップ2でクライアント側の安全性チェックに使用）。

ステップ2：デフォルトグループのリリースブランチを取得する

dxs --output json source branch list \
  --repo <REPO_ID> --default-group --status published -n 0

• --default-group は、リポジトリのデフォルトアプリケーショングループを対象にします（Service Pack グループは除外されます）。
• --status published は、applicationStatusId=3 のブランチに絞り込みます。以前のリリースのステータスは降格されません。PublishedMain のまま保持され、releaseDate と isLatest によって区別されます。
• -n 0 はページングを無効にし、すべてのリリースを取得します。

リリースごとに必要なフィールド：id、releaseDate、versionName、marketplaceApplicationVersionId、isLatest。

CLIが各ブランチに既知のグループIDを付与するため、クライアント側でグループをフィルタリングする必要はありません。結果は確定的です。（ステップ1で取得した defaultApplicationGroupId は、将来CLIが変更された場合に備えた健全性チェックとしてのみ保持します。）

ステップ 3：2 つの基準ブランチを選択する

フィルタリングしたリリースをreleaseDateの降順で並べ替えます。次を選択します。

• last_before — releaseDateがrange_startより厳密に小さいエントリのうち、releaseDateが最大のもの。
• last_in_range — range_start ≤ releaseDate ≤ range_endを満たすエントリのうち、releaseDateが最大のもの。

次の 3 つの結果すべてを明示的に処理します。

1. last_in_rangeがない — 期間内にリリースがありません。1 行の要約を出力します。

   「<range_start>から<range_end>まで、のリリースはありません。」

   停止します。release-notes-generatorは呼び出さないでください。

2. last_in_rangeはあるが、last_beforeがない — 初回リリースです。last_in_range.versionName、releaseDate、およびブランチレコードにreleaseNotesのテキストがあれば、それを要約した短い初回リリースノートを出力します。停止します。差分を比較するベースラインがないため、release-notes-generatorは呼び出さないでください。

3. 両方がある — ステップ 4 に進みます。

ステップ 4：release-notes-generatorに委譲する

release-notes-generatorスキルを次の引数で呼び出します。

• --from = last_before.id
• --to = last_in_range.id

release-notes-generatorスキルは、比較 → 作業項目 → 差分 → 依存関係 → 作成のパイプラインを処理し、技術者向けと顧客向けの両方のバリエーションを作成して、必須の作業項目リンク／ビジネスコンテキスト／作成者の要件を適用します。このガイダンスをここで重複させないでください。既存のスキルを参照することで、SOP の進化に合わせて両者の内容を常に同期できます。

オペレーターが、対象のスキルに渡すためのエンリッチメント済み構造化ペイロードを 1 つだけ必要とする場合は、dxs source release-notes --from <…> --to <…> --enrich-workitems --output jsonコマンドで取得できます。このペイロードを返すのはdxs ≥ 0.5.4であり、それより前のバージョンでは依存関係の更新が一切ないかのようにサイレントに報告されます。それ以外の場合は、ブランチ ID のみを渡してrelease-notes-generatorに独自のコマンドを実行させても問題ありません。これがデフォルトです。

ステップ 5：ノートを返す

技術者向けと顧客向けのノートを、エージェントの応答として返します。このスキルは、出力をナレッジノード、ファイル、メッセージングチャネルには保存しません。配信方法は呼び出し元（スケジューラー、ユーザー、後続の自動化）が決定します。

ヒント

1. タイムゾーン。 releaseDateはオフセット付きの ISO 8601 形式です。比較の前に、これとrange_start／range_endを同じタイムゾーン（UTC が最も安全です）に変換してください。タイムゾーンが異なると、リリースが期間内に入ったり、期間外になったりする可能性があります。
2. サービスパックによるノイズ。 --default-groupを指定しない場合、dxs source branch list --repo <id>はサービスパックを含むすべてのグループのブランチを返します。週の途中のサービスパックのホットフィックスがlast_in_rangeとして選ばれ、比較に影響する可能性があります。--default-groupを指定すれば防げます。
3. createdDateとreleaseDate。 リリースブランチでは数ミリ秒しか違いませんが、このスキルでは意味的なフィールドであり、将来のスキーマ変更にも問題なく対応できるreleaseDateを使用します。
4. 冪等性。 同じ(app, range_start, range_end)で実行を繰り返すと、公開済みリリースは不変であるため、同じ基準ブランチの組み合わせが返されます。安全に再実行できます。
5. スケジュール設定は外部です。 Windows Task Scheduler、cron、Azure Functions、手動実行のいずれも、同じ方法でこのスキルを起動します。スケジューラーは対象範囲外です。このスキルでは、呼び出された後の作業のみを説明します。
6. リリースがない週は通常どおりです。 リリース頻度の低い週のほとんどは、ステップ 3 で結果 1 になります。「今週はリリースなし」は有効で想定内の結果であり、失敗ではありません。

セッションの例

# Range: 2026-04-13 00:00 UTC → 2026-04-19 23:59:59 UTC
# Application: "thedevapp" in organization "Datex"

# Step 1
dxs --output json organization search "Datex"
# → id: 1 (Datex)

dxs --output json organization app list --org 1
# → name=="thedevapp": id=1, defaultApplicationGroupId=1

# Step 2
dxs --output json source branch list --repo 1 --default-group --status published -n 0
# → branches:
#     id=60  releaseDate=2026-01-06  isLatest=true
#     id=3   releaseDate=2025-10-23  isLatest=false

# Step 3 — anchors for [2026-04-13, 2026-04-19]
# last_before   = branch 60   (largest releaseDate strictly before range_start)
# last_in_range = none          (no release inside the range)
# → Outcome 1: emit "No releases between 2026-04-13 and 2026-04-19 for thedevapp" and stop.

# If last_in_range had existed, Step 4 would run:
#   invoke release-notes-generator with --from=60 --to=<last_in_range.id>

よくある間違い

間違い	修正方法
最初に一致した組織／アプリを無条件で選ぶ	一致が0件または複数件の場合はエラーにし、候補と対処方法を表示します
--default-group を省略する	Service Pack のブランチが一覧に混入し、アンカーがずれる可能性があります
並べ替えに releaseDate ではなく createdDate を使う	意味上のフィールドである releaseDate を使います
last_in_range がないのに release-notes-generator を呼び出す	結果1：1行の要約を出力して終了します
「初回リリース」のケースを忘れる	結果2：「Initial Release」の注記を出力し、比較対象がない状態で差分を取らないでください
スキル内に出力を保存する	このスキルはテキストのみを返します。呼び出し元が配信を処理します
範囲の比較でタイムゾーンが一致していない	比較前にすべてをUTCに変換します