audit-ml-pipeline

ML パイプラインの監査

skore レポートの実験ごとの、人が読みやすいナラティブです。 # %% ファイルは人が読むノートブックであり、実行されません。materialize.py はダイジェストと HTML ビューアーを 1 回の実行で書き出します。skore Project に対して読み取り専用です。

ユーザー向けの文章

詳細：setup-workspace references/human_facing_prose.md。 監査の Markdown と # コメントでは、このレポートの調査結果を説明します ――スキルのフレームワーク、CLI、出力を生成したコマンドについてではありません。質問、回答、最後のナラティブでは、 スキル ID、G-* 名、ラッパー CLI ではなく、同じデータサイエンス用語を使います。末尾のロケータートークンはインデックス文字列のままにします。audit/<stem>.py に API チュートリアル、バージョンの下限、ロケーターの手順を記載しないでください。`` はサイトマーカーです。 執筆時のヒントはこのスキル内に置きます。style は ruff のみです。

次のステップへのポインター

ここに来た経路…	監査後の次のステップ…
model-ml-pipeline（ループの実装）	→ 戻ります。この監査の実行ですでにノートブックがマテリアライズされている場合があります。呼び出し元は record-outcome の前に、鮮度ゲートとして python -m skore_skills loop notebooks --stem <stem> を実行し、その後サイトをビルドして git end-turn --stage implement を実行します。
ユーザーの自由入力（「audit 02」、「re-audit 04」）	→ メトリクスを提示してから、締めくくりを担当します（§ ターンの終了を参照）
既存の実験の再実行	→ 既存の監査ファイルを再実行します。メトリクスが変わっていれば差分を提示します

実装ループは、evaluate の後、record-outcome の前に監査を実行します。ダイジェストにはチェックの概要とメトリクスの概要が含まれます。G-AUDIT-FINDING は、そのダイジェストから導出される、別個の正規化された所見です。 manage-ml-backlog の record-outcome は両方を取り込み、監査を再度実行することはありません。

保存場所 — 視覚的なマップ

パス	保持性	書き込むもの	内容
audit/<NN>_<short_name>.py	永続的（git 内）	このスキル。実験ごとに 1 回	式のみのセルです。信頼できる唯一の情報源です。エージェントは実行しません。サイトのノートブックは、このファイルから出力を空にしたものです
scratch/audit/<stem>/audit.md	一時的（gitignore 対象）	materialize.py	チェック表示とメトリクスフレームの repr です。audit finding がこれを解析します
scratch/results/<stem>/materialize.py	一時的（gitignore 対象）	Evaluate。evaluate-ml-pipeline/templates/materialize.py から	唯一の skore.evaluate と project.put です。report.html、report.txt、id.txt、checks.html、metrics.html、Method ビューアーを書き出します
scratch/results/<stem>/report.html report.txt locator.txt id.txt pipeline/ または pipeline.html	一時的（gitignore 対象）	Evaluate の materialize.py。その後、エージェントが id.txt から locator.txt を書き込みます	フルレポートビューアー、テキストのフォールバック、ロケーター、DataOp レポートまたはグラフのフォールバック
scratch/audit/<stem>/materialize.py	一時的（gitignore 対象）	このスキル。templates/materialize.py から	レポートを再度開きます。チェック、メトリクス、audit.md、追加のビューアー、および accessors.txt を書き出します
scratch/audit/<stem>/accessors.txt	一時的（gitignore 対象）	materialize.py	help() のツリーです。追加のレポート表示ラベルはノートブックではなく、ここにある Displays グループから取得します
scratch/results/<stem>/checks.html metrics.html および追加の <slug>.html / .png	一時的（gitignore 対象）	materialize.py	サイトが ## Results の下に埋め込む、項目ごとのビューアーです。ダイジェストにはすでにテキストが含まれているため、ここでは追加の .txt は書き出されません
実行ダイジェスト	CLI 出力またはダイジェストのパスから取得	CLI	ストリーム出力または書き出されたダイジェストです。エージェントはこれを直接読み取ります

覚え方： audit/ は ソース（git 内）で、scratch/audit/ と stdout は 出力 です。audit/<stem>.py を scratch/audit/ にコピーしないでください。materialize.py は gitignore 対象のエージェントスクリプトです。 scratch/audit/ 配下のものは、絶対にコミットしないでください。

読み取り専用の契約

中心となるルールです。以下の最初の停止条件に示しています。

audit/<stem>.py で許可される操作：

• skore.Project(...) — この実験の書き込み先プロジェクトを開きます。
• project.summarize() — (key, id) のペアを一覧表示します。
• project.get(id) — id を指定して特定のレポートを読み込みます。
• すべての report.* アクセサー。
• <pkg> からのインポート（読み取り専用の確認）。

audit/<stem>.py で禁止される操作：

• skore.evaluate(...) — 同じキーでレポートを重複させ、 summarize() を汚染します。
• project.put(...) — 同様です。
• スナップショットの書き込み（HTML の write_text、 locator.txt、 report.txt）および audit/<stem>.py での help() ループ。これらは scratch/audit/<stem>/materialize.py に置きます。このファイルは scratch/results/<stem>/ および accessors.txt に書き込む場合があります。
• data/、reports/、src/<pkg>/ への書き込み。監査ノートブックはビューアーです。
• セルの実行後も残る、読み込んだ report の変更（例： skore シンボルへのモンキーパッチ）。

ランナーは各セルのソース、最後の式の repr、 stdout をすべてダイジェストに出力します。禁止された呼び出しはダイジェストに表示されます（後続の summarize() セルに put 行として、または **error:** セクションとして表示されます）。この契約は見えるものであり、見えないものではありません。

同種の読み取り専用コンシューマー（出力形式は異なりますが、同じ規律に従います）：scratch/<ts>_*.py プローブ。review-ml-experiment はダイジェストをテキストとして読み取り、Project は開きません。コンシューマーのルールについては evaluate-ml-pipeline の § 停止条件を参照してください。

停止条件 — まずこれを読んでください

• セットアップがまだ完了していません。 まず python -m skore_skills status を実行してください。status.setup.pending が空でなく、status.skills.setup-ml-project が true の場合は、setup-ml-project を読み込んで停止してください。このスキルを開始してはいけません。戻ってきたら続行してください。このターンでは再度読み込まないでください。そのスキルがインストールされていない場合は、保留中の項目を1行で挙げて停止してください。git init、scaffold、env init を捏造してはいけません。status.setup.env または status.setup.workspace が declined の場合は、1行で停止してください。git または editable が declined の場合は再確認せず、続行してください。
• レポートがなければ → 停止。 4者の組み合わせは必須です。python -m skore_skills design consent --stem <stem>（ask／stop → 監査しない）＋ experiments/NN_*.py ＋ スモーク pytest の合格 ＋ Project 内のそのキーに対応するレポートが必要です。レポートが見つからない場合は、説明して停止してください。skore.evaluate／project.put を実行してはいけません。evaluate-ml-pipeline または model-ml-pipeline に振り分けてください。直接の「audit 02」にも同じゲートを適用します。
• skore Project に対して読み取り専用です。 § Read-only contract を参照してください。監査ファイルで skore.evaluate(...) または project.put(...) を実行してはいけません。
• project.get(...) はキーではなく ID を指定します。 ハブモードでは、project.put() が出力する URL から ID を読み取ってください。 https://…/<workspace>/<project>/<type-plural>/<N> → ID は skore:report:<type-singular>:<N> です（URL のセグメントは複数形ですが、ID では単数形を使います。末尾の s を削除してください。例：cross-validations → cross-validation、estimators → estimator）。監査ファイルに REPORT_ID をハードコードしてください。summarize() をたどる必要はありません。 ローカルモードでは、一致するキー行の project.summarize() の "id" 列を読み取ってください。get("<stem>") による KeyError は、レポートが存在しないことではなく、検索方法が誤っていることを意味します（get は ID を指定します）。
• 記憶からのシンボル指定は禁止です。 skore／skrub／sklearn のシンボルは、必ずこのターンに python -m skore_skills api get を実行して取得してください。scratch/api/skore/<version>/ にあるキャッシュヒットは該当します（Shape 0）。記憶からのインライン指定は該当しません。
• エージェント機能がない場合 → 停止して委任します。 ipython／ipython をインポートできない場合、代替策として print() 呼び出しを書いて監査出力を捏造してはいけません。自分で pixi add ...／uv add ... と入力してはいけません。インストールは add-python-package § Agent feature の担当です。agent tools (ruff / ipython / ipykernel) を通じて依頼してください（バイナリ：install／skip）。add-python-package が「ready」を返した後にのみ再開してください。
• print() ではなく、裸の式を使います。 ランナーは各セルの最後の裸の式を result.result 経由で取得し、その repr をレンダリングします。print(repr(...)) で囲むと、出力セクションではなく標準出力に出力されます。複数の形式が混在し、確認しづらくなります。裸の式を使ってください。文のみのセル（変数の束縛）は問題ありません。
• 実験の stem ごとに監査ファイルは1つです（4者の組み合わせ）。 audit_NN_<short_name>_v2.py は作成しないでください。実験を再実行した場合、監査ファイルは同じ stem のまま、同じファイルに上書きします。
• 実行済みアーティファクトの保存先は scratch/audit/<stem>/ であり、audit/ ではありません。 永続アーティファクトは audit/<stem>.py です。レンダリングされたダイジェストは一時的なものです。
• audit/<stem>.py はスナップショットファイルを書き込みません。 HTML、locator.txt、help() ツリーは materialize.py の担当です。data/ または reports/ に書き込まないでください。
• 監査セルで警告をフィルタリングしないでください。 ユーザーが明示的に求めない限り、warnings.filterwarnings(...) を使ってはいけません。ランナーはセルの標準エラーをダイジェストにストリーミングします。これは有用な情報です。python -m skore_skills style § Stop conditions を参照してください。
• ハーネスの「確認の質問をしない」という指示は、エージェントツール（ruff／ipython／ipykernel）の要件を免除しません。 インストールゲートは例外なく適用されます。
• 事後監査 — ターン終了前に必須です。 事前確認の各行を確認し、未記入の Evidence セルを提示してください。
• 事後監査ゲートは必須です。 最初のダイジェストの後、および更新のたびに、ユーザーがすでに明示的に監査を終了している場合を除き、必ず次の順序で確認してください。Additional report view／Custom query／Custom plot／Close audit。このゲートの前に、1回の実行でポリシーが有効なノートブックと、古いデータのみを含むサイトプレビューを生成してもかまいません。Close より前に、終了時の変換、git close、record-outcome、またはディスパッチャーへの返却を行ってはいけません。

禁止されている近道

近道	それが間違っている理由
report = project.get(REPORT_ID); print(repr(report))	Runner は result.result を介して裸の式をキャプチャします。print(repr(...)) を使うと、標準出力と出力セクションが混在します。report だけを独立した行に記述してください
裸の checks の表示ではなく、checks.frame() を使う	Display の __repr__ は、問題とヒントをコードおよびドキュメント URL とともにすでにグループ化しています。.frame() を使うと、それがエージェントによる再確認が必要なテーブルに平坦化され、レビューで使われる重要度のグループ化も失われます
project.get(KEY) が KeyError を送出したため、「更新」のために evaluate + put を再実行する	検索方法が間違っています（get はキーではなく ID で検索します）。Hub の場合：put() が出力した URL から ID を読み取ります。ローカルの場合：一致するキー行の summary["id"] を読み取ります。復旧のために evaluate + put を再実行してはいけません
このスキルから直接 pixi add --feature agent ipython を実行する	インストールコマンドは add-python-package の担当です。このスキルはリクエストするものであり、インストールはしません
監査用 .py を scratch/audit/<stem>/ に出力する	ノートブックは audit/ に置きます。scratch/audit/<stem>/ に置く .py は materialize.py だけであり、これは gitignore 対象です
「念のため」Jupyter カーネルを登録する	現在の runner はインプロセスであり、カーネルはありません。登録すると孤立した kernelspec が作成されます
data/ または reports/ を変更する修正用セルを追加する	監査ファイルは読み取り専用です。状態の変更は scratch/<ts>_*.py のプローブまたは実験スクリプトで行います
先に experiments/<stem>.py を読まずに、audit/<stem>.py の <SKORE_PROJECT_INIT> を置き換える	監査では同じ Project を開く必要があります。このターンで必ず experiments/<stem>.py を読み、Project の初期化ブロックを（書式を除き）バイト単位で同一にコピーしてください
Hub モード：skore.login(mode="hub") を skore.Project(...) の後に置く	Project(...) コンストラクターは初期化時に認証します。先に login を呼び出さないと失敗します。順序は固定です：先に login、次に Project
実装ループの監査後に「指標を再確認する」ため、最初にスクラッチプローブを書く	監査そのものが指標抽出の手順です。このディスパッチが置き換えるアンチパターンが、指標用スクラッチプローブです
audit/<stem>.py 内で write_text または help() ループを使う	ノートブックは人間が見るためのものです。HTML、ロケーターファイル、accessors.txt を生成するには、templates/materialize.py を scratch/audit/<stem>/materialize.py にコピーしてください

事前確認 — 監査ファイルの書き込みまたは実行の前に出力する

Pre-flight (audit-ml-pipeline):
- [ ] Experiment stem confirmed: <NN_short_name>
      Evidence: journal/NN_<short_name>.md exists AND state is approved
                | "n/a — user invoked re-audit on existing stem"
- [ ] Four-way pairing complete:
        journal/NN_<short_name>.md       — design note (state approved or done)
        experiments/NN_<short_name>.py   — script
        tests/smoke/test_NN_<short_name>.py — smoke test (passing)
        audit/NN_<short_name>.py         — about to be written / refreshed
      Evidence: ls / Glob on each path
- [ ] Report present in skore Project under key=<NN_short_name>
      Evidence: project.summarize() this turn; row with
                key == "<NN_short_name>" appears.
                "Run finished, put() landed" is NOT sufficient.
- [ ] Agent feature available:
        run `ipython -c "print(0)"` and `ipython --version`
        through the project's composed dev environment
      Evidence: tool output of each
                | JOURNAL.md Status `agent feature: installed`
                Missing → STOP, delegate to add-python-package agent tools (ruff / ipython / ipykernel)
- [ ] API CLI consulted for skore symbols used:
      Project, summarize, get, report.checks.summarize, report.metrics.summarize
      Evidence: Read scratch/api/skore/<version>/<topic>.md (this turn)
                | Write the same (this turn)
                | "n/a — cache hit, file already on disk + Read this turn"
- [ ] Template copy + substitution decided:
        <pkg> → package name from src/<pkg>/
        <NN>_<short_name> → experiment stem
        <SKORE_PROJECT_INIT> → literal block copied from experiments/<stem>.py
      Evidence: Read experiments/<stem>.py this turn for the Project init block;
                Read templates/audit.py this turn before Write audit/<stem>.py
- [ ] Read-only contract acknowledged: audit file contains
      summarize / get / report.* only — no evaluate, no put
      Evidence: explicit grep / Read confirmation of the drafted file
- [ ] Execution command shape confirmed:
        python scratch/audit/<stem>/materialize.py
        notebooks true: notebook fill audit/<stem>.py [--html]
      Evidence: command emitted in the response before running
- [ ] G-AUDIT-FINDING derived from the executed digest
      Evidence: issue/tip counts + ordered codes + optional metric
                context | explicit clean-checks value
- [ ] Post-audit gate answered: additional view | query | plot | close
- [ ] Pre-flight re-emitted with evidence before final message.
      Evidence: this checklist appears in the end-of-turn summary.

実行前

4 項目の対応付け、レポート検索、エージェント機能、API の各確認が完了したら、audit/<stem>.py の書き込みまたは実行の直前に、自然な文で 1～3 文を出力します。これは再トレーニングではなく、ローカルでの読み取り専用レポートの実体化であることを伝えます。永続化された Skore レポートを開き、チェック／指標／利用可能なビューをレンダリングし、ダイジェストを scratch/audit/<stem>/ に、HTML ビューアーを scratch/results/<stem>/ に書き込むことを説明します。ポリシーに一致する正確な実行コマンドを明記します。

コストは事実に基づいて説明します。レポートの読み込みと要求されたビューのレンダリングであり、モデルのフィッティングや完全な CV ではありません。観測済みの所要時間がない限り、所要時間はレポートのサイズと選択したビューによって異なると伝え、分数を推測してはいけません。このプレビューは初回の監査で一度だけ出力し、Additional report view／Custom query／Custom plot によって作業内容が大きく変わる場合にのみ更新します。実行は既存の監査後ゲートで一時停止します。

レポートの意味に関する質問は、ダイジェストを対象とするLLM の説明作業です。チェックが発火した場合は、そのドキュメント URL を読み、該当ページの推奨事項を適用してください。これらの処理で evaluate や put を呼び出すことはありません。必須ゲートが保留中の場合は、監査のプレビューは行いますが、書き込みも実行もしません。

監査ファイルの仕様 — 概要

監査ファイルはjupytext のパーセント形式（# %%）です。ファイル名： audit/NN_<short_name>.py — stem は実験と完全に一致させます。 テンプレート：templates/audit.py。

置換

プレースホルダー	置換後
<pkg>	インポート可能なパッケージ名（src/<pkg>/ から取得）
<NN>_<short_name>	実験の識別名（例：02_target_transform）
<SKORE_PROJECT_INIT>	Project の完全な初期化ブロック（ハブモードの場合は、その前にある skore.login(...) の呼び出しも含む）。experiments/<stem>.py からコピーし、バイト単位で完全に同一にすること
<project-name>	experiments/<stem>.py の name= 引数（内容を読み取り、作り出さないこと）
<hub-workspace>	ハブモードの場合のみ。experiments/<stem>.py の workspace= 引数からコピーすること
<REPORT_LOCATOR>	evaluate から引き渡される、put 後に正規化されたロケーター。存在しない場合は、選択した ID と以下のバックエンド規則から導き出すこと。URL を推測しないこと

<SKORE_PROJECT_INIT> と <project-name> は、置換を誤りやすい項目です。監査では、実験が書き込んだものと同じ Project を開く必要があります。このターンでは必ず experiments/<stem>.py を Read して、そのままの初期化ブロックを取り出してください。skore mode: の判断だけを記憶に頼って再構成してはいけません。

セルの構成（各セルの役割）

簡単な概要です。具体例を含む詳細な構成については、 references/cell_anatomy.mdを参照してください。

1. モジュールの docstring（Markdown セル） — このファイルの内容と、読み取り専用のルールを記述します。
2. インポート（コードセル） — import skore、from <pkg> import ...。
3. プロジェクトを開く（式のみのセル） — project = skore.Project(...)を実行し、続けてprojectを単独の行に記述します。
4. レポートを一覧表示する — summary = project.summarize()を実行し、続けてsummaryを記述します。
5. レポートを読み込む — project.put()が出力したURLからREPORT_IDを設定します（Hubの場合："skore:report:<type-singular>:<N>"。URLのパスセグメントは複数形、IDは単数形です。例：cross-validations → cross-validation、estimators → estimator。local および mlflowの場合：該当するキーの行からsummary["id"]を読み取ります）。次にreport = project.get(REPORT_ID)を実行し、最後の式としてreportを記述します。このセルではHTMLやlocator.txtを書き込まないでください。 それはmaterialize.pyが行います（api getで_repr_html_を確認してください）。
6. 永続化されたレポート — evaluateから取得した、正規化済みの正確なロケーターに置き換えます。直接監査する場合は、選択したREPORT_IDとpolicy.skore_modeを使用します。localのリンクは../reports/、Hubでは保存されたputの正確なURL（またはプロジェクトへのリンクであることが明確なもの）を使用します。MLflowでは、出力されたrun URLを使用するか、tracking URI＋experiment id＋run idを記録します。信頼できるロケーターがない場合は、n/a — backend did not expose a locatorと記述します。putを呼び出したり、非公開のストレージを調べたり、フロントエンドURLを作り出したりしないでください。
7. チェックの概要 — checks = report.checks.summarize()を実行し、最後の式としてchecksを記述します。materialize.pyがchecks.htmlを書き込みます。そのreprでは、ウォーク結果が重大度ごとにグループ化されます。各issue／tip行の末尾にはドキュメントURLがあります。そのページを読み、推奨事項を適用してください（カスタムのCSTM*チェックには推奨事項がない場合があります）。
8. メトリクスの概要 — metrics = report.metrics.summarize().frame(verbose_name=True, flat_index=False)を実行し、最後にmetricsを記述します。materialize.pyはそのフレームからmetrics.htmlを書き込みます。このフレームだけをメトリクステーブルとして使用します。その値を設計メモにも重ねて記載しないでください。
9. 利用可能なレポートアクセサー — ノートブックのセルではありません。templates/materialize.pyをscratch/audit/<stem>/materialize.pyにコピーして実行します。report.metrics、report.checks、存在するその他の名前空間（inspection、dataなど）に対してhelp()を呼び出し、そのツリーをaccessors.txtに書き込みます。help()はツリーを出力し、Noneを返します。存在しない名前空間はスキップしてください。ここではプロットアクセサーを呼び出さないでください。ループをaudit/<stem>.pyに記述しないでください。

これが基本のテンプレートです。チェックは単独の式として表示してください。エディターは_repr_html_をレンダリングし、ランナーはreprを記録します。また、.frame()では重大度ごとのグループ化が失われます。メトリクスは上記のフレームを使用し、その表示や別のMarkdownテーブルは使用しません。追加の表示セルは、ユーザーがAdditional report viewを選択した後にのみ追加します。詳細：→ references/cell_anatomy.md。

ダイジェストはレビューの正式な情報源です

レンダリングされたダイジェスト scratch/audit/<stem>/audit.md は、review-ml-experiment が journal/ideas/<stem>-<slug>.md と journal/JOURNAL.md の Ideas 行を作成する際に参照する唯一の信頼できる情報源です。このスキルはダイジェストをテキストとして読み取り、## Checks summary 内の Issues:、次に Tips: を確認します。Project を再度開いたり、report.* を呼び出したり、メトリクスの抽出に scratch/<ts>_*.py のプローブを書き込んだりすることはありません。 その後、manage-ml-backlog がこれらのファイルをトリアージします。アイデアが採用されると、Ideas テーブルから削除され、Backlog 行になります。

契約の範囲は、永続化されたレポートのロケーター、チェック、メトリクスの概要に限定されます。レビューで追加の Display 見出しを確認してはいけません。 コアテンプレートに ROC、confusion-matrix、importance のセルを 追加しないでください。Close-audit の追加セル以降では、それぞれのセルに独自の ## <title> 見出しを使用します。ユーザーが、accessors.txt に記載されていないカスタム図を明示的に求めた場合は、 セルを書き込む前に、インストールされていれば plot-ml-figure を読み込みます。skore Display を置き換えてはいけません。PNG（または HTML）を保存して図を表示したままにしてください。監査ノートブックで plt.close を呼び出してはいけません。

G-AUDIT-FINDING

監査の実行が成功するたびに、 python -m skore_skills audit finding --stem <stem> を実行するか、ダイジェストのパスを渡します。JSON の finding をそのまま貼り付けてください。コード、件数、メトリクスの文節を書き換えてはいけません。ダイジェストがない場合、JSON の finding は n/a — audit digest unavailable です。

追加の Display セルは G-AUDIT-FINDING に影響しません（コマンドを再実行しても、チェックとメトリクスのみが読み取られます）。

ダイジェストと、python -m skore_skills loop locator --stem <stem> で取得した G-REPORT-LOCATOR とともに、G-AUDIT-FINDING をそのまま返してください。manage-ml-backlog はこの所見を設計ノートの Status ブロックに書き込みます。ビュー、クエリ、図を追加するたびにダイジェストが上書きされるため、所見を再計算してください。

監査を続ける

最初の要約の後、および更新が成功するたびに、ユーザーがすでに終了すると述べている場合を除き、次の順序で選択肢を1つだけ提示して AskUserQuestion を行います。どの選択肢も推奨・事前選択しません。

ゲートのコンテキスト。 質問の前に、回答によって許可されることと、その根拠となる事実（このターンの要約からそのまま引用する、読み取ったばかりのチェックとメトリクス、および accessors.txt の表示名）、さらに各選択肢で行うことを2～4行で述べます。ファイルリンクは追加情報であり、コンテキストの代わりにはなりません。

ラベル	契約
追加レポートビュー	メニューのラベルは、このターンの scratch/audit/<stem>/accessors.txt にある Displays グループの名前と完全に一致させます。選択された名前を python -m skore_skills api get で確認します。リストはタスクに依存します。回帰レポートに roc はありません。ツリーにないものは省略し、記憶している表示名を決して表示しません。編集前に選択肢を1つ提示します。
カスタムクエリ	読み込まれたレポートについて、具体的な読み取り専用の質問が1つ来るまで待ちます。回答に必要な最小限のアクセサーセルだけを、audit/<stem>.py と materialize の <CALL> ブロックに追加します。ツリー内の名前で質問に答えられる場合は、その名前を優先します。
カスタムプロット	ツリーにこのチャートの表示がない場合に限ります。status.skills.plot-ml-figure が true の場合に限り plot-ml-figure を読み込みます。それ以外の場合は、1行でスキップしてこのゲートに戻ります。読み取り専用のプロットを両方のファイルに追加します。materialize.py は図を scratch/results/<stem>/ に保存します。
監査を終了	既存のディスパッチ経由または直接の終了処理に進みます。

追加レポートビュー／カスタムクエリ／カスタムプロットは、いずれも同じ永続的な audit/<stem>.py の ## Core audit complete より下、および materialize.py の <CALL> ブロックを編集します。編集後は、style を実行し、materialize.py を1回再実行し、ノートブックが有効な場合は notebook fill を実行し、python -m skore_skills audit finding --stem <stem> で G-AUDIT-FINDING を再生成し（チェックとメトリクスのみ）、サイトポリシーが true の場合は site build --if-stale を実行して、この同じゲートを再提示します。「監査を終了」を選ぶ前に、終了時の loop notebooks を実行したり、git end-turn、record-outcome を実行したり、ディスパッチャーに戻ったりしないでください。監査は読み取り専用のままです。evaluate、put、ワークスペースデータの変更は禁止です。

追加の Display セル

スラッグ = accessors.txt の Displays に記載されたアクセサー名です。ドキュメントの記憶を頼りにスラッグを作らないでください。

1. Markdown セル ## <人向けのタイトル> — ## Checks summary または ## Metrics summary にはしません。
2. コードセル：アクセサーを呼び出し、返された Display に対して api get で _repr_html_ を確認します。最後の式は Display そのものにします。
3. materialize.py だけで、そのアクセサーを EXTRA に追加します。_repr_html_() が存在する場合は scratch/results/<stem>/<slug>.html に書き込みます。存在しない場合に限り <slug>.png を保存し、サイトに図を埋め込めるようにします。materialize.py を再実行します。
4. 失敗したアクセサーや該当しないアクセサーは scratch/ のプローブに残します。それらの Results サブセクションは追加しません。

manage-ml-backlog は、追加された各 <slug> ビューアー（report、checks、metrics 以外）を、### の Results 見出しと ``, に変換し、生成元となったダイジェストセルの内容に基づいて要約します。

実行契約 — 1 回の実行

ある stem で最初に実行する前に、 python -m skore_skills review consent --stem <stem> を実行します。

• stop — 不足している report.html の名前を示して停止します。
• audit — audit/<stem>.py を作成し、1 回実行します。 結果がレポートとともに保存されていることを確認します。この読み取りではそれらを使用します。
• proceed — ダイジェストが存在します。ユーザーが再監査を明示的に依頼していない限り、実行しないでください。再監査では、ポリシーに適合した 1 回の実行を繰り返します。

templates/materialize.py を scratch/audit/<stem>/materialize.py にコピーし、Project の初期化、レポート ID、ロケーターを置き換えてから、env verify の composed-dev Python で 1 回実行します。この実行により、HTML ビューアー、accessors.txt、audit.md が書き出されます。監査ファイルを cells run したり、notebook convert したりしないでください。 policy.notebooks が true の場合は、次を実行します。

python -m skore_skills notebook fill audit/<stem>.py [--html]

--html を追加するのは、site も true の場合だけです。Fill は出力のないノートブックを書き出しますが、ダイジェストは書き出しません。notebooks が null または false の場合は、ポリシーを変更せず、fill も実行しないでください。その後、次を実行します。

python -m skore_skills audit finding --stem <stem>

ノートブックには、materialize による書き込みは含まれません。site ポリシーが true で、export-ml-site がインストールされている場合は、materialize の後、ゲートの前に python -m skore_skills site build --if-stale を実行します。ビルドが実行された場合は、ウェブサイトが更新されたことを伝え、ブラウザーで開くための report.html へのリンクを付けます。デザインノートの Markdown や html/<stem>.html の名前は出さないでください。

JSON の finding をそのまま貼り付けます。audit.md を読み、ノートブックから内容を導き出さないでください。

実行済みノートブック

ノートブックポリシーが true の場合、上記の notebook fill が、直接実行とディスパッチ経由の両方で出力のないノートブックを管理します。呼び出し元は python -m skore_skills loop notebooks --stem <stem> を実行し、convert に対してはカーネルで実行するのではなく、fill を行います。notebook fill と記載するだけでは、その呼び出しにはなりません。現在のソースフィンガープリントがあればゲートはスキップされます。ソースが変更された場合は、安全策として再度 fill されます。

直接クローズする場合は、record-outcome の前に「§ ターン終了」のノートブックゲートを実行します。監査専用のページはありません。site ポリシーが true の場合、audit/<stem>.nb.html が存在すれば、サイトビルドによってデザインノートの ## Notebooks セクションに埋め込まれ、評価ノートブックの後に配置されます。`` は追加しないでください。マーカーを追加してもビューアーは作成されず、.nb.html がなければ省略されます。

再実行のセマンティクス

• 実験を再実行する（同じキーで put() を上書きする） → 対応する監査ファイルを再実行します。manage-ml-backlog § 4 は、record-outcome のたびにこれを実行します。
• 監査ファイルのソースを編集する（メトリックアクセサーを追加するなど） → 再実行します。ダイジェストは再生成できます。
• scratch/audit/<stem>/ は、実行のたびに上書きされます。バージョン履歴はありません。監査証跡はソース .py と git の履歴です。

4 項目の stem ペアリング規則

setup-workspace のペアリング規則を、成果物 3 つから 4 つに拡張します。

journal/NN_<short_name>.md           — design note
experiments/NN_<short_name>.py       — script
tests/smoke/test_NN_<short_name>.py  — smoke test
audit/NN_<short_name>.py             — audit  ← this skill

stem は同一で、1 対 1 です。実験が journal/JOURNAL.md で done になる時点までに、4 つすべてが存在します。

ディスパッチの開始元と終了先

呼び出し元

呼び出し元	タイミング
review-ml-experiment	レビュー同意が audit の場合、アイデアファイルの作成前
model-ml-pipeline	このスキルは読み込みません。review-ml-experiment を読み込みます
evaluate-ml-pipeline	単独の評価では、クローズ前に監査を実行する場合があります
ユーザーの自由記述	「実験 02 を監査して」「03 を見せて」「04 を再監査して」など。直接解決されます

呼び出し先

呼び出し先	理由
python -m skore_skills audit finding	監査の実行後。JSON の finding をそのまま貼り付けます
python -m skore_skills loop locator	locator.txt または監査ファイルから G-REPORT-LOCATOR を取得します
python -m skore_skills loop artifacts	直接監査の締めくくり：ノートブックのゲート前に record を実行します
python -m skore_skills loop notebooks	record-outcome の前に実行します。convert に従ってください。skip で続行します
add-python-package	ipython が見つからない場合
manage-ml-backlog (record-outcome モード)	直接の自由記述監査のターン終了時に、ダイジェストを引き継いで History 行とデザインノートの Status ブロックを作成します
python -m skore_skills style	audit/<stem>.py の作成・編集後に実行します。バンドルされた ruff.toml には audit/** のファイル単位の除外設定が含まれています。Ruff のみを実行し、コメントは書き換えません。監査ファイルにワークフロー／プロセスの説明を書かないでください

ターン終了時

ディスパッチされた場合（このターンで model-ml-pipeline、evaluate-ml-pipeline、または manage-ml-backlog が呼び出された場合）、Close audit の後に次を実行します：python -m skore_skills audit finding --stem <stem> と python -m skore_skills loop locator --stem <stem>。呼び出し元にダイジェスト、JSON finding、JSON locator、任意の 見出しを返します。そこで終了します。ここでは record-outcome、 close 時の loop notebooks、別のサイトビルド、 git end-turn、トリアージを実行しないでください。上記の実行中の処理／プレビューは繰り返しません。呼び出し元が model-ml-pipeline または evaluate-ml-pipeline の場合は、python -m skore_skills loop notebooks --stem <stem> を実行し、record-outcome の前に notebook fill を使って convert に従うよう指示します。このゲートは skip でも続行します。record は loop artifacts であり、ノートブックのゲートではありません。その後、site build と呼び出し元の git end-turn を実行します（model からは --stage implement、evaluate からは --stage evaluate）。fill コマンドを挙げることは close ではありません。監査ファイルだけを埋めても close は完了しません。 ディスパッチャーが実行する内容のプレビューとして、直接監査の close を貼り付けないでください。

直接の自由形式テキスト監査の場合、Close audit の後： このスキルが close を担当します。Close audit より前に開始しないでください。まず python -m skore_skills loop artifacts --stem <stem> を実行します（record が想定されます）。record はこのコマンドのアクションであり、ノートブックのゲートではありません。その後、次の順序で実行します。順序を変えないでください。 loop notebooks は skip の場合にのみ続行します。

1. python -m skore_skills loop notebooks --stem <stem>。JSON の action を正式な判断基準として扱います。action が convert の間は、record-outcome、 site build、git end-turn を実行しないでください。 not_evaluated は convert ではありません。
2. convert の場合は、experiments/ または audit/ のソースごとに notebook fill を実行し、html が true の場合は --html を指定します。それらのファイルに notebook convert を実行しないでください。fill は put を実行しません。現在の成果物を書き出した実行以降に人間による呼び出し内容が変更された場合に限り、対応する materialize.py を先に再実行します。action が skip になるまで手順 1 を再実行します。jupytext / nbformat が不足している場合は、add-python-package を指定した1行の skip を返します。監査を失敗させず、pixi add も実行しないでください。
3. status.skills.manage-ml-backlog が true の場合に限り、manage-ml-backlog を record-outcome モードで読み込み、ダイジェスト、G-AUDIT-FINDING、その locator を渡します。スキルがない場合は1行の skip を返します。ここで History を書き込まないでください。このモードは記録して返すものであり、このスキルを再ディスパッチするものではありません。smoke が赤の間は done にしないでください。
4. policy.site が true で export-ml-site がインストールされている場合に限り、次を実行します： python -m skore_skills site build --if-stale。mkdocs-material is required でエラーになった場合は、mkdocs-material 用に add-python-package を読み込み（agent）、もう一度ビルドします。pixi add / uv add は実行しないでください。ビルドエラーを明示し、監査を失敗させないでください。
5. ユーザー向けの close。メッセージは Checks + Metrics をもとに2～6文で作成します。メトリクスを捏造したり、ダイジェストを貼り付けたりしないでください。手順4が成功した場合は、ウェブサイトが更新されたことを伝え、ブラウザーで開くためのリンク [report.html](<workspace>/report.html) を示します。html/<stem>.html や journal/<stem>.md の名前を出さないでください。サイトをビルドしなかった場合は、更新されたと主張せず、markdown の名前も出さないでください。その後、手順2の JSON locator をそのまま記載し（ローカルの場合は絶対パスの reports/ も記載）、続けて G-AUDIT-FINDING を記載します。文章ではなくインデックス文字列を使ってください。 ディスパッチされた監査では、このメッセージは出力しません。
6. python -m skore_skills git end-turn --stage evaluate。監査は evaluate ステージを続行します。audit ステージはありません。JSON の action が invoke の場合は、status.skills.persist-ml-git が true の場合に限り persist-ml-git を読み込み、終了します。そのスキルはトリアージに戻ります。persist がない場合は、保留中の staged パスを明示して終了します。それ以外の場合は、status.skills.triage-ml-task が true の場合に限り triage-ml-task を読み込み、それ以外は終了します。このスキルでは git commit を実行しないでください。

失敗モードと復旧

簡易参照です。詳細な復旧手順は references/failure_modes.md を参照してください。

症状	原因	対処
project.get(key) が KeyError / TypeError を発生させる	ID ではなくキーで検索しています。ローカルと Hub で形式が異なります	→ references/failure_modes.md § 「project.get(key) raises」
ModuleNotFoundError: No module named 'IPython'	エージェント機能がインストールされていません	add-python-package に委任してください。ここで pip install を実行しないでください
セルが <Display object at 0x…> としてレンダリングされる	Display にテキスト表現を与えるには skore のバージョンが古すぎます	そのセルにのみ .frame() を追加し、ほかはそのままにしてください
report.* アクセサーで AttributeError が発生する	記憶に頼ったシンボル、または skore のバージョン変更です	→ references/failure_modes.md § 「AttributeError」
RuntimeError: No report under key=...	put() が別の Project に適用されました	→ references/failure_modes.md § 「wrong Project」
ソースに変更がないのに、実行ごとにレポートが異なる	非決定的なステップ、または異なるデータスライスです	ここでのバグではありません。ユーザーに伝えてください
Hub モード：skore.login() の認証エラー	トークンの期限切れ、または初回ログインです	→ references/failure_modes.md § 「skore.login fails」
Hub モード：TypeError: workspace キーワード引数	Hub 形式にローカルモードのキーワード引数が残っています	→ references/failure_modes.md § 「TypeError workspace」
Hub モード：put() 後に summarize() でレポートが見つからない	Hub ワークスペースが違う、または読み取りアクセス権がありません	→ references/failure_modes.md § 「report missing」

このスキルが行わないこと

• skore Project のレポートを開いたり書き込んだりすること（evaluate-ml-pipeline の担当です）。
• ipython をインストールすること（add-python-package の担当です）。
• journal/ideas/ ファイルや Ideas の行を書き込むこと （どちらも review-ml-experiment の担当です）。
• journal/NN_*.md または journal/JOURNAL.md を直接書き込んだり編集したりすること。ターンの最後に manage-ml-backlog の record-outcome モードをディスパッチしてください。 ジャーナルへの書き込みはすべてこのスキルの担当です。
• pytest / スモークテストを実行すること（smoke-test-ml-pipeline の担当です）。
• コミットや PR をレンダリングすること。
• どの メトリクスが重要かを判断すること。セルにはタスクごとの値が入りますが、 何が重要かの判断は設計ノートに記載されているとおり、ユーザーが行います。

関連スキル

スキル	関係
manage-ml-backlog	後続の record-outcome コンシューマーです。record-outcome モードから監査をディスパッチすることはありません
review-ml-experiment	ループの呼び出し元です。ダイジェストをテキストとして解析し、候補ごとにアイデアファイルを 1 つ、Ideas の行を 1 つ書き込みます。Project は開きません
evaluate-ml-pipeline	生成側です。実験ファイルに呼び出しが記載され、実行は materialize.py のみです
setup-workspace	ワークスペースのレイアウト、4 方向のステムのペアリング
add-python-package	エージェント機能のインストール（エージェントツール（ruff / ipython / ipykernel））。このスキルがリクエストし、あちらのスキルがインストールします
python -m skore_skills api get	help や追加の Display メソッドを含む skore シンボルの検索。まずキャッシュヒットを確認します
plot-ml-figure	accessors.txt に Display がない場合に限る、カスタムプロットのゲートです
python -m skore_skills style	audit/<stem>.py の書き込み／編集後に実行する ruff
choose-python-library / python -m skore_skills env stack	エージェントツール（ipython、ipykernel）はエージェント機能に含まれます

テンプレートとアセット

• templates/audit.py — 実験ごとの監査ファイルのひな形です。コピーして 置き換えてください。記憶を頼りに書き直さないでください。表示はそのままにしてください。
• templates/materialize.py — 監査の実行はこれのみです。コピーして scratch/audit/<stem>/materialize.py に配置します。HTML ビューアー、accessors.txt、audit.md を書き込みます。

パッケージが必要ですか？

インポートが見つからない場合、status.skills.add-python-package が true なら add-python-package を読み込んでください。env add と管理対象外の依頼はそのスキルの担当です。ここで env add を実行しないでください。 そのスキルがインストールされていない場合は、パッケージ名を伝えて終了してください。

参考資料（必要に応じて読み込んでください）

• references/cell_anatomy.md — 具体的なセルの例（正しい形式／誤った形式）、基本的な順序、チェックを単独の Display にし、メトリクスで frame(verbose_name=True, flat_index=False) を使用する理由、追加の Display スナップショットの仕様、単独式のルール。
• references/runner_internals.md — 残りのランナー内部情報（IPython、Agg）。--help またはパッケージの docstring を優先してください。
• references/failure_modes.md — § Failure modes にある各症状への詳細な対処方法。