Plan comment

計画コメント

親 issue に1件だけ置き、進行に応じて同じコメントを編集して更新する。

答えるべき問い

読み手は issue を見に来た人間である。 次の3つに答えられていれば、その計画コメントは役目を果たしている。

1. いま人間がすべきことは何か(マージ待ちの PR、裁定待ちの triage)
2. どこで止まっていて、それが何を堰き止めているか
3. 親要件の取りこぼしはないか

答えを本文の先頭に置く。 図はこの答えを補強するときだけ足す。

構成

必須は次の2つだけである。

• 冒頭の要約:上の3つの問いへの答えを1〜2行で書く
• 一覧表:子ごとに issue リンク、対応する親要件、状態、PR、予算

図は下の条件を満たすときだけ足す。

図に描くもの

図は「各子で何を作るか」を描く。依存関係だけの図にしない。 issue 番号を並べて矢印で結んだだけの図は、下の一覧表が持っている情報の再掲であり、読み手は何が作られるのかを読み取れない。

子ごとに、その issue が生む具体の成果物と手順を2〜4個のノードで書き、子の枠(subgraph)にまとめる。 子と子のあいだの辺には、何を受け渡すのかをラベルで書く(「メタ情報を参照」「異常系を追加」など)。

その子が生む具体を書く(定義するデータ構造、追加する関数やコマンド、接続する箇所、用意するデータセット、算出する指標など)。

抽象的な工程名(「実装」「テスト」)をノードにしない。 その issue を読まなくても何が作られるか分かる粒度にする。

図を描く条件

上の中身を持たせたうえで、表では表せない構造があるときだけ描く。 次のいずれかを満たすことを確認してから描く。

• 合流または分岐がある(入次数または出次数が2以上の子がある)
• レイヤーが3段以上ある
• 子が5件以上ある

満たさないなら描かない。 子が1件か2件で一直線なら、各子が作るものを箇条書きで書けば足りる。

要件カバレッジの図も同じ判断による。 親要件と子が1対1で対応しているなら描かない(それは表の1列である)。 1つの親要件を複数の子で分担する、1つの子が複数の親要件をまたぐ、対応する子が無い親要件がある、のいずれかがあるときに描く。 孤児の親要件があるなら、それを図の主役にする。

状態の決め方

ラベルと PR の状態から決める。

状態	判定
完了	子 PR が統合ブランチへ取り込み済み(merged)
進行中	loop:in-progress、または gate:start-passed 以降で未 ready
差し戻し	gate:*-returned
裁定待ち	loop:triage
未着手	依存待ち、または未処理

凡例は、実際に出現した状態だけを本文の1行として書く。 図の中に凡例のノードを作らない(レイアウトエンジンが凡例を本体と同格のノードとして配置し、図の主役を奪うため)。

更新

同じコメントを編集して更新する。 新しい計画コメントを増やさない。 子の集合が変わった場合は、最新の計画コメントを正とする。

図の記法と図種の選び方は tasuki:mermaid skill を参照する。