PJR-2W38 sample の品質が他種別より著しく低い
1. 概要
kata の走査で、sample の評価が他種別より著しく低い。走査は継続中のため確定値ではないが、 判断材料を失わないよう途中観測を記録する。
本 note は走査の進行に伴って更新する。終端させない。
2. 観測（2026-09-07 時点、全4種別の走査完了）
数値は generated/ 配下を除いた正本のみを対象とする。生成物は他の正本から作られる派生物で、 直接編集しても再生成で失われるため評価の対象にしない。
2.1. 種別間の比較（確定値）
| 種別 | n | pass | needs-work | fail | score 中央値 |
|---|---|---|---|---|---|
| rulebook | 100 | 44（44%） | 55（55%） | 1（1%） | 91 |
| recipe | 18 | 14（78%） | 4（22%） | 0 | 100 |
| sample | 87 | 18（21%） | 34（39%） | 35（40%） | 69 |
| template | 32 | 24（75%） | 6（19%） | 2（6%） | 100 |
| 合計 | 237 | 100 | 99 | 38 | — |
sample だけが突出して低い。fail は blocker の存在を意味し、rulebook は 1 件、recipe は 0 件、 template は 2 件である。score 中央値も sample の 69 に対し他は 91 から 100 である。
2.2. 3段目の判定（確定値）
ローカルが pass とした文書を codex が精査した結果である。
| 種別 | codex も pass |
|---|---|
| rulebook | 7 / 29（24%） |
| recipe | 3 / 12（25%） |
| sample | 5 / 10（50%） |
| template | 12 / 20（60%） |
sample と template はローカルが pass とした文書を codex も認める割合が高い。ただし sample は そもそも pass が 21% と少ないため、母数が小さい。
2.3. 要修正の総量
needs-work と fail の合計は 137 件である。
| 種別 | 要修正 | 割合 |
|---|---|---|
| rulebook | 56 | 56% |
| recipe | 4 | 22% |
| sample | 69 | 79% |
| template | 8 | 25% |
| 合計 | 137 | 58% |
sample が 69 件で全体の半数を占める。
2.4. 生成物が結果を歪めていた
走査の途中まで generated/ 配下を対象に含めていた。sample では 9 件が該当し、除外の前後で 数値が変わる。
| 区分 | 件数 | pass | fail | 中央値 |
|---|---|---|---|---|
| 生成物のみ | 9 | 5 | 0 | 96 |
| 正本のみ | 87 | 18 | 35 | 69 |
生成物は fail がゼロで中央値 96 と高く、正本の評価を実際より良く見せていた。走査対象から generated/ を除外し、以後は正本だけを評価する。
2.5. blocker の観点
| 観点 | 件数 |
|---|---|
vp-qe-kata-conformance | 12 |
vp-qe-omissions-consistency | 11 |
vp-ux-readability | 2 |
vp-arc-cross-document-consistency | 1 |
8 割が 2 観点に集中する。
2.6. 指摘の内容
サンプルとして成果物の具体的な記述例を示す責務を果たしておらず、
ルールブックの標準定義を全く適用していない。
本文書は BDS のサンプルとして定義されているが、
BDS ルールブックの構成案および命名規則に一切準拠していない。3. 検証
数字だけで結論せず、指摘が事実かを規範と突き合わせて確認した。
3.1. 構成の乖離
br-sample.md を対応 rulebook と比較した。
br-rulebook が定める本文構成 | br-sample の実際の構成 |
|---|---|
| 概要 / 入力 / ルール / 出力 / 例外 / メモ | 目的と適用範囲 / 入力情報 / 記述内容 / 最小記述例 / 未解決事項 |
構成が一致しない。指摘は事実である。
3.2. 定型構成の共有
複数の sample が同一の章立てを持つ。
| sample | 章構成 | 性質 |
|---|---|---|
| bds | 目的と適用範囲 / 入力情報 / 記述内容 / 最小記述例 / 未解決事項 | メタ文書 |
| bes | 同一 | メタ文書 |
| ccd | 同一 | メタ文書 |
| dec | 背景 / 検討した選択肢 / 決定内容 / 採択理由 | 完成例 |
多くの sample が「sample の書き方を説明する文書」になっており、完成例になっていない。 dec-sample は成果物としての構成を持つため、全件が同じ状態ではない。
3.3. 規範との照合
sample-authoring-standard.md は次を定める。
- rulebook の必須要素を満たす最小例を提示し、抽象的な規約を具体的な記述へ変換する
- 必須章をすべて満たしつつ、最小の記述量で完成例として成立させる
- sample は対応 rulebook を一次根拠とし、必須要件を満たす最小記述例に再構成するsample は完成例であるべきと明記されている。メタ文書は規範に反する。
したがって「評価基準が sample に合っていない」という解釈は否定される。評価は正しく、 sample 側に実際の問題がある。blocker の付与も妥当である。
4. 見積もりと影響
全4種別で要修正は 137 件（58%）である。うち sample が 69 件で半数を占める。
観測の途中で見積もりを2度誤った。25 件時点で「45 件前後」と述べ、39 件時点で「35〜40 件」へ 訂正した。前者は初期の偏った標本、後者は一時的な改善局面を見ての判断だった。確定値の 35 件は 後者の範囲に収まる。
sample の修正は軽微でない。章構成から書き直す必要があり、指摘は「一切準拠していない」「全く 適用していない」という水準である。一方 rulebook の 56 件は needs-work が主で、blocker は 1 件 にとどまる。修正の重さは種別で異なる。
修正へ渡す経路は既に存在する。maintenance と bootstrap の exec テンプレートに finding を 参照する指示が含まれており、exec plan --approach <kind>-maintenance で生成した plan へ反映 される。当初これを「経路がない」と誤認して prj-0001:pjr-9py9-maintenance-plan-findings を 起票したが、前提が誤っていたため reject した。
ただし 137 件に対して実際に maintenance を回した実績はない。経路の存在と、それが機能する ことは別である。
4.1. 着手の優先順位
| 順 | 対象 | 根拠 |
|---|---|---|
| 1 | sample | fail 35 件。完成例として機能しておらず利用者への影響が大きい |
| 2 | rulebook | 要修正 56 件だが blocker は 1 件。指摘は個別の欠落が主 |
| 3 | template | 8 件。母数が小さい |
| 4 | recipe | 4 件。品質が最も高い |
sample は rulebook の規約を具体化する役割を持つ。ここが機能しないと rulebook を読んでも 書き方が伝わらない。修正の優先度が最も高い。
5. 今後
- 全4種別の走査が完了し、数値は確定した。
- 対処方針が定まった時点で、実施のための todo を別途起票する。本 note は観測の記録に留める。
dec-sampleのように完成例として成立しているものがあるため、全件一律ではなく個別に判定する。- 走査対象から
generated/を除外した。以後の評価は正本だけを対象とする。
6. 関連ドキュメント
- prj-0001:pjr-49d2-quality-assessment: 品質評価の起点。
- prj-0001:pjr-9py9-maintenance-plan-findings: 修正経路。本観測により重要度が上がる。
- specdojo:sample-authoring-standard: sample が満たすべき規範。