pms-01-kb

Imported from yuminyamo/smoke (.github/skills/pms-01-kb/SKILL.md). Install upstream with npx skills add yuminyamo/smoke --skill pms-01-kb. Copyright stays with the author.

作業01 知見蓄積(手順版 proc-v010)

この skill は、手順書の正本の stages.md §01 を本文とし、作業に必要な規約・語彙・付録・記入用テンプレートを references/ に同梱したものである。本文(下の「---」以降)が指示である。

起動時に読むもの(この順で。省略しない)

1. .github/skills/pms-01-kb/references/00_common.md を全文読む(全作業に適用される既定)
2. .github/skills/pms-01-kb/references/vocab.yaml を全文読む(統制語彙)
3. 作業場所の kb/00_索引.md を読む(KB は索引のみ。全読みしない。00 ■知見ベース)
4. 対象フローがあれば、作業場所の work/_flows/F-<番号>/flow.md を読み、現在地と手順版を確かめる
5. 付録と記入用テンプレートは、本文で参照されたときに下の表のファイルを開く

本文の呼び名と、このskillのファイル

手順書を書き換えない

この skill と references/ は、正本(procedure/)から生成したものである。手順について迷った・矛盾を見つけた・実行できなかった・手順と違う方法で実施した場合は、書き換えずに手順改善シグナルとして記録する(00 ■手順改善シグナル)。status.yaml の procedure_version には proc-v010 をそのまま転記する。

8スロット規約(本文の読み方)

各作業の節は、必ず以下の8スロットをこの順で持つ。該当なしの場合も見出しを残し「なし」と書く。 空欄は仕様の穴として扱う。

節番号とスロット番号は、手順改善シグナルが手順箇所を指すための位置(vocab.procedure_location の ST)でもある。番号を付け替えない。

各節の見出しの直後には、ノードIDの行に続けて参照付録と参照テンプレートの行を置く(書式: 参照付録: A, B / 参照テンプレート: 91, 94。該当なしは「なし」)。この行は、その作業の skill に同梱する付録と記入用テンプレートを決める(00 ■AIへの渡し方)。本文で付録・テンプレートを新たに参照したら、この行にも加える。

§01 知見蓄積

ノードID: kb / クラス: .operate,.text 参照付録: E / 参照テンプレート: 91, 93, 94

1. 役割

あなたは対象システムの調査者である。人間が指示した調査対象について、自動回帰テスト作成の各作業が何を必要とするかを逆算し、有用と推測される情報を調査してKBに記録する。人間は調査項目を列挙しない。何を調べるべきかの推測はあなたの仕事である。

達成すべきは「発見活動をゼロにすること」ではない。同じ発見が二度起きないことである。

2. 起動条件

3. 入力

4. 固有手順

S1: 調査範囲の逆算(最重要)

各作業が何を必要とするかを逆算し、調査項目を自分で立てる。 以下を出発点とする(これに限らず、有用と判断した項目は追加してよい)。

逆算の例(指示: 「複合機からジョブログを収集する操作」): 「ジョブログ」がドメイン用語として何を指し画面では何と表示されDBのどのテーブルか / 収集操作は T05 のどの操作IDか(未登録なら使える skill を確認し、あれば使い方を確立して登録、なければ外部操作需要リストへ記録) / 完了をどう判定するか・所要時間の実測 / 結果をどの画面で確認できるか・到達経路とロケータ / ステータス値の一覧はどの文書にあるか / 収集前後でどのテーブルが変化するか・課金レコードとの関係 / 収集直後にレコードが即座に見えない等の癖はあるか。

S1の出力として、調査項目の一覧と、それぞれがどの後段作業のために必要かを1文で示す。 この一覧を報告書の冒頭に置く。

S2: 文献調査(ポインタの記録)

• 対象に関する記述の所在を特定する
• 本文を転記・要約しない。 記録するのは「何が、どの文書の、どこに書かれているか」(例: ジョブステータスの一覧と遷移: PMS仕様書 v12.3 / 5.2章)
• 記述が見つからなかった項目は**「文書に記載なし」として明示的に記録する**(後段が探し直さないため。「見つからなかった」ことも知見である)
• 文書間で記述が矛盾している場合は、両方のポインタと矛盾の要点を記録し、DISC候補として報告する

S3: DB定義と蓄積データの調査

• INFORMATION_SCHEMA(TABLES / COLUMNS / KEY_COLUMN_USAGE / REFERENTIAL_CONSTRAINTS)から、対象に関係するテーブルの定義・PK/FK・NULL可否・型を機械抽出する
• 実際に蓄積されているデータを観測する(SELECT のみ)。列の意味は定義だけでは分からないことが多い
  • 例: ステータス列に実在する値の一覧、金額列が予測系か実績系か、日時列が更新のたびに変わるか
  • 実在値の一覧は仕様書の記載と突き合わせる。文書にあるが実データに存在しない値(死んだenum値)、実データにあるが文書にない値はどちらも重要な知見
• 機械抽出部と注記部を明確に分離し、機械抽出部を手で編集しない(再抽出で上書きされる前提)
• 課金スキーマ(95 Q-001)に関係する調査を行った場合、結果を判断材料として95に参照リンクする。裁定はしない

S4: 実操作による調査

Web画面操作(主たる手段):

• 調査を始める前に node tools/env/env.mjs require で環境情報を確かめる。調査に要る値(外部操作の対象機器の接続先など)が足りなければ --keys に加え、まとめて人間に聞いて保存する(00 ■検証環境の情報)。KB には値ではなくキーを書く
• 前提の基本操作は既存の fixture・シナリオ部品を実行して作る(00の資産流用規約)。自分で操作を編み出すのは、調査対象そのものの操作と、資産が存在しない前提操作に限る
• 対象に関係する画面へ到達し、URL・画面タイトル・主要要素・安定ロケータ・遷移経路を記録する
• ロール別の可視性差(管理者/一般ユーザー)を確認する
• テスト環境に対しては書き込み操作を行ってよい(データを作らないと観測できない知見が多いため)。実施した変更は報告書の「環境への影響」に記録する

外部操作(必要な場合): 印刷指示、機器パネル操作等。00の ■外部操作 に従い、skill を介してのみ行う。

• KB T05 に確立済みの操作があればそれを使う。なければ skills の機構で使える skill(実行体を同梱したもの)を確認し、あれば使い方を確立して T05 に登録する
• 使える skill がなければ、調査対象そのものの操作であっても実行を試みず、外部操作需要リストに記録する(要求元は 作業01:<調査対象>)。その操作に依存する調査項目は「判明しなかったこと」として報告する
• 非同期処理を伴う操作は、同一操作を3回実行して所要時間を実測し、タイムアウト根拠(実測値の3倍程度)を算出して T06 に記録する

観測の記録原則: 「何をしたら何が起きたか」を、再現できる粒度で書く。曖昧な要約(「正常に動作した」等)を残さない。

S5: KBへの反映

• 付録Eのカテゴリ別フォーマットに従って書き込む
• 全エントリに00のレビューヘッダと、付録Eの共通メタデータ(出所コード・確度・観測日)を付ける
• kb/00_索引.md を更新する
• ファイルは vocab.default.kb_file_lines 行以内を目安に分割する

カテゴリの拡張機構

カテゴリ(T01〜T11)は統制語彙だが、AIによる暫定追加を認める。 追加してよい条件(いずれか):

1. 既存カテゴリに割り当てられない発見ログエントリが累計3件以上になった
2. gotchas/ 内に同種とみなせるエントリが2件以上再発した
3. ステップ2・3への移行で新たな知見需要が生じた

手続き: レジストリ(kb/01_知見対象レジストリ.md)に unreviewed の行として追記し、テンプレートを作成し、索引を更新する。追加理由(どの条件を満たしたか、該当する発見ログのエントリ)を必ず書く。根拠のない追加は禁止。

申し送り台帳の理由コードには、この暫定追加を適用しない。 理由コード別の集計がそのままステップ2・3の投資計画になる統制語彙であり、AIが勝手に語彙を増やすと集計の意味が壊れるため。KBのカテゴリは集計対象ではなく格納場所の分類なので暫定追加を許容する、という線引きである。

一定期間(目安: バージョン更新2回分)参照実績のないカテゴリは、廃止・統合の候補として報告する。廃止時はファイルを削除せず kb/_archived/ へ移す。

5. 固有の禁止事項

• 人間の指示なく本作業を開始しない
• マニュアル・仕様書の本文をKBに転記・要約しない(ポインタのみ)
• 「分からなかったこと」を報告せずに済ませない
• KBに判断・推測を事実として書かない(推測と明示するか、DISCへ回す)
• 指示された対象から無制限に調査範囲を広げない(広げた場合は範囲と理由を報告する)
• 網羅的な事前ドキュメント整備を目指さない。KBの完成はパイプライン開始の前提条件ではない

6. 出力

報告書の固有セクション:

1. 調査項目の一覧(S1の出力。各項目がどの後段作業のために必要か)
2. 判明したこと: KBに書いた内容の要約と、書き込んだファイルの一覧
3. 判明しなかったこと: 調べたが分からなかった項目と理由(文書に記載なし / 実機で確認できない / 禁止操作に該当 / 外部操作の skill がない・確立できず 等)。後段が同じ調査を繰り返さないために必須
4. DISC一覧とAIの見立て
5. KB T05 へ新規登録した操作ID
6. 外部操作需要リストへの記録(新規追加・要求元を追記した需要IDと不足の区分)

7. 完了条件(DoD)

• S1の調査項目一覧を出力し、各項目にどの後段作業のためかを1文で添えた
• 全調査項目について、判明した / 判明しなかった のいずれかを記録した
• 文献調査の結果がポインタのみで、本文の転記・要約を含まない
• 「文書に記載なし」と判明した主題を明示的に記録した
• KBの全エントリにレビューヘッダと共通メタデータ(出所・確度・観測日)がある
• kb/00_索引.md を更新した
• skill を使って新たに確立した外部操作を KB T05 に登録し、操作IDを報告書に列挙した
• 使える skill がなく実行できなかった外部操作を全件、外部操作需要リストに記録した(既存行があれば要求元の追記)
• 発見ログに記録した(再発見・矛盾フラグを含む)
• 実施した書き込み操作と残留データを「環境への影響」に記載した
• 報告書 §8 に、本作業で記録した手順改善シグナルのID(なければ「なし」)を列挙した
• status.yaml を出力した

8. status.yaml 契約

stage: "01"
context_updates:
  knowledge_gap_resolved: yes | no      # exp から escalation で来た場合、解消したか
  kb_entries_added: <件数>
  kb_t05_registered: [<操作ID>, ...]
  ext_demand_added: [<需要ID>, ...]      # 外部操作需要リストに新規追加
  ext_demand_appended: [<需要ID>, ...]   # 既存の需要に要求元を追記
  env_keys_added: [<キー>, ...]          # 新たに保存した環境情報のキー(値は書かない。なければ省略可)
  unresolved_subjects: [<主題>, ...]     # 判明しなかった項目
  escalation: none | permission_required
  nd_needed: yes | no                    # 調査中に未収載の非決定値が見込まれた場合 yes