Imported from yuminyamo/smoke (
.github/skills/pms-01-kb/SKILL.md). Install upstream withnpx skills add yuminyamo/smoke --skill pms-01-kb. Copyright stays with the author.
作業01 知見蓄積(手順版 proc-v010)
この skill は、手順書の正本の stages.md §01 を本文とし、作業に必要な規約・語彙・付録・記入用テンプレートを references/ に同梱したものである。本文(下の「---」以降)が指示である。
起動時に読むもの(この順で。省略しない)
.github/skills/pms-01-kb/references/00_common.mdを全文読む(全作業に適用される既定).github/skills/pms-01-kb/references/vocab.yamlを全文読む(統制語彙)- 作業場所の
kb/00_索引.mdを読む(KB は索引のみ。全読みしない。00 ■知見ベース) - 対象フローがあれば、作業場所の
work/_flows/F-<番号>/flow.mdを読み、現在地と手順版を確かめる - 付録と記入用テンプレートは、本文で参照されたときに下の表のファイルを開く
本文の呼び名と、このskillのファイル
| 本文での呼び名 | ファイル |
|---|---|
00_common.md・「00」・「00 ■〇〇」 |
.github/skills/pms-01-kb/references/00_common.md |
vocab.yaml・vocab.〇〇 |
.github/skills/pms-01-kb/references/vocab.yaml |
| 付録E(KBカテゴリ別フォーマット) | .github/skills/pms-01-kb/references/appendix-E.md |
| テンプレート91 | .github/skills/pms-01-kb/references/templates/91_申し送り台帳_記入用.md(書式の原本。記入先は本文が示す work/ 配下) |
| テンプレート93 | .github/skills/pms-01-kb/references/templates/93_外部操作需要リスト_記入用.md(書式の原本。記入先は本文が示す work/ 配下) |
| テンプレート94 | .github/skills/pms-01-kb/references/templates/94_手順改善台帳_記入用.md(書式の原本。記入先は本文が示す work/ 配下) |
pipeline.dot・stages.md の他の節・上にない付録 |
この skill には含まれない。読まない(他の作業の関心を混ぜないため。00 ■AIへの渡し方) |
| 上にない記入用テンプレート | 書式が必要なら、作業場所の記入済みの台帳(work/_common/ 配下)の既存の行に合わせる |
手順書を書き換えない
この skill と references/ は、正本(procedure/)から生成したものである。手順について迷った・矛盾を見つけた・実行できなかった・手順と違う方法で実施した場合は、書き換えずに手順改善シグナルとして記録する(00 ■手順改善シグナル)。status.yaml の procedure_version には proc-v010 をそのまま転記する。
8スロット規約(本文の読み方)
各作業の節は、必ず以下の8スロットをこの順で持つ。該当なしの場合も見出しを残し「なし」と書く。 空欄は仕様の穴として扱う。
| # | スロット | 内容 |
|---|---|---|
| 1 | 役割 | この作業のAIが何者か。1〜3文 |
| 2 | 起動条件 | pipeline.dot のノードIDと、この節に入る条件 |
| 3 | 入力 | 成果物IDの一覧のみ。レビューヘッダの確認義務は00の既定なので書かない |
| 4 | 固有手順 | この作業にしかない手順。00にある規約は参照1行で済ませる |
| 5 | 固有の禁止事項 | 00の既定にないものだけ |
| 6 | 出力 | 成果物ID+スキーマ参照+ゴールド例参照+報告書の固有セクション |
| 7 | 完了条件(DoD) | チェックリスト。全項目を満たすまで完了報告を出さない |
| 8 | status.yaml 契約 | この作業が書く context_updates のキーと取りうる値 |
節番号とスロット番号は、手順改善シグナルが手順箇所を指すための位置(vocab.procedure_location の ST)でもある。番号を付け替えない。
各節の見出しの直後には、ノードIDの行に続けて参照付録と参照テンプレートの行を置く(書式: 参照付録: A, B / 参照テンプレート: 91, 94。該当なしは「なし」)。この行は、その作業の skill に同梱する付録と記入用テンプレートを決める(00 ■AIへの渡し方)。本文で付録・テンプレートを新たに参照したら、この行にも加える。
§01 知見蓄積
ノードID: kb / クラス: .operate,.text
参照付録: E / 参照テンプレート: 91, 93, 94
1. 役割
あなたは対象システムの調査者である。人間が指示した調査対象について、自動回帰テスト作成の各作業が何を必要とするかを逆算し、有用と推測される情報を調査してKBに記録する。人間は調査項目を列挙しない。何を調べるべきかの推測はあなたの仕事である。
達成すべきは「発見活動をゼロにすること」ではない。同じ発見が二度起きないことである。
2. 起動条件
| 項目 | 内容 |
|---|---|
| ノード | kb |
| 進入元 | pre(context.kb_requested=yes — 人間がフロー開始前に指示)、または exp からの context.escalation=knowledge_gap |
| 位置づけ | 任意。人間の指示があったときだけ実行する。 パイプラインの必須工程ではない |
| 退出先 | nd(context.nd_needed=yes)または exp |
3. 入力
| 成果物ID | 所在 |
|---|---|
| 調査対象 | 人間の指示(例: 「複合機からジョブログを収集する操作」) |
| 既存資産 | tests/fixtures/・tests/flows/(前提操作の成立に使う)、kb/00_索引.md |
| 文献 | マニュアル・仕様書・設計書 |
prohibited-ops |
work/_common/prohibited-operations.md(外部操作を行う場合) |
ext-demand |
work/_common/external-op-demand.md(外部操作需要リスト) |
| 外部操作 skill | skills の機構で確認する(00 ■外部操作) |
| 環境情報 | node tools/env/env.mjs(接続先・アカウント。開始時に require で確かめる。00 ■検証環境の情報) |
4. 固有手順
S1: 調査範囲の逆算(最重要)
各作業が何を必要とするかを逆算し、調査項目を自分で立てる。 以下を出発点とする(これに限らず、有用と判断した項目は追加してよい)。
| 後段の作業 | その作業が必要とする知見 | KBカテゴリ |
|---|---|---|
| 02 非決定値カタログ | 値が画面のどこに出るか、DBのどの列に入るか、操作の反復に必要な操作列、環境の癖 | T01 / T03 / T09 |
| 10 シナリオ生成(パートB) | 業務用語と画面表記とDB名称の対応、画面の所在と到達経路、ロール別の可視性、外部操作の可否(確立済みか、使える skill があるか)、根拠にできる文書の章番号 | T08 / T01 / T07 / T05 / T11 |
| 10 探索的実行(パートC) | 画面の到達方法・主要要素と安定ロケータ、操作起因の遷移、確立済み操作の台帳(再探索の回避)、外部操作の前提と挙動、非同期の完了判定条件と実測時間、既知の落とし穴 | T01 / T02 / T05 / T06 / T10 |
| 20 コード生成 | 待機条件とタイムアウト根拠、アサーションに使えるDB列、セレクタ | T06 / T03 / T01 |
| 30 状態カタログ | 状態がどの操作で成立するか、状態をどこで確認できるか(画面/DB) | T01 / T02 / T03 / T07 |
| DB不変条件(INV) | テーブル・列の意味、主キー・外部キー、NULL可否、1対Nの関係 | T03 |
逆算の例(指示: 「複合機からジョブログを収集する操作」): 「ジョブログ」がドメイン用語として何を指し画面では何と表示され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値)、実データにあるが文書にない値はどちらも重要な知見
- 機械抽出部と注記部を明確に分離し、機械抽出部を手で編集しない(再抽出で上書きされる前提)
- 課金スキーマ(
95Q-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による暫定追加を認める。 追加してよい条件(いずれか):
- 既存カテゴリに割り当てられない発見ログエントリが累計3件以上になった
gotchas/内に同種とみなせるエントリが2件以上再発した- ステップ2・3への移行で新たな知見需要が生じた
手続き: レジストリ(kb/01_知見対象レジストリ.md)に unreviewed の行として追記し、テンプレートを作成し、索引を更新する。追加理由(どの条件を満たしたか、該当する発見ログのエントリ)を必ず書く。根拠のない追加は禁止。
申し送り台帳の理由コードには、この暫定追加を適用しない。 理由コード別の集計がそのままステップ2・3の投資計画になる統制語彙であり、AIが勝手に語彙を増やすと集計の意味が壊れるため。KBのカテゴリは集計対象ではなく格納場所の分類なので暫定追加を許容する、という線引きである。
一定期間(目安: バージョン更新2回分)参照実績のないカテゴリは、廃止・統合の候補として報告する。廃止時はファイルを削除せず kb/_archived/ へ移す。
5. 固有の禁止事項
- 人間の指示なく本作業を開始しない
- マニュアル・仕様書の本文をKBに転記・要約しない(ポインタのみ)
- 「分からなかったこと」を報告せずに済ませない
- KBに判断・推測を事実として書かない(推測と明示するか、DISCへ回す)
- 指示された対象から無制限に調査範囲を広げない(広げた場合は範囲と理由を報告する)
- 網羅的な事前ドキュメント整備を目指さない。KBの完成はパイプライン開始の前提条件ではない
6. 出力
| 成果物 | 所在 | 書式 |
|---|---|---|
| KBエントリ | kb/ 配下 |
付録E |
| KB索引 | kb/00_索引.md |
— |
| 発見ログ | logs/discovery-log_YYYYMMDD.md |
00 |
| 外部操作需要リスト | work/_common/external-op-demand.md |
テンプレート93 |
| 手順改善シグナル | work/_common/procedure-improvement.md |
00 ■手順改善シグナル / テンプレート94 |
| 報告書 | 当該調査の作業ディレクトリ | 00の共通骨格 + 下記 |
| status.yaml | 同上 | スロット8 |
報告書の固有セクション:
- 調査項目の一覧(S1の出力。各項目がどの後段作業のために必要か)
- 判明したこと: KBに書いた内容の要約と、書き込んだファイルの一覧
- 判明しなかったこと: 調べたが分からなかった項目と理由(文書に記載なし / 実機で確認できない / 禁止操作に該当 / 外部操作の skill がない・確立できず 等)。後段が同じ調査を繰り返さないために必須
- DISC一覧とAIの見立て
- KB T05 へ新規登録した操作ID
- 外部操作需要リストへの記録(新規追加・要求元を追記した需要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