clinical-note-extract-skill

臨床ノートの抽出

ユーザー定義のスキーマに基づいて臨床ノートから構造化データを抽出し、すべての値に根拠箇所の引用を付け、存在しないものはすべて明示的に null にします。ノートが1件でも複数件でも手順は同じです。ツールを持たない分離されたワーカーが各ノートを抽出し、その後、決定論的な検証パスで引用箇所とコードを確認します。

これは、ケアギャップの推論、有害事象の検出、治験適格性のスクリーニング、事前承認の根拠資料の作成、レジストリの抽象化を支える抽出の基本機能です。

手順

1  Define schema   — references/01-define-schema.md
2  Extract         — workflows/extract-batch.js (one isolated worker per note)
3  Validate        — span check + run each field's `check`
4  Report          — references/03-review.md

ステップ 1 — スキーマを定義する

references/01-define-schema.md を読みます。ユーザーのリクエストをスキーマに変換します。各フィールドは {desc, finding?, check?} です。desc には、ノート内で使われている表現に沿って探す内容を記述します。finding: true は主張を分類することを意味します。check はステップ3で検証する方法です（自由形式で、{kind: "terminology"|"range"|"date"|"pattern"|"enum"|..., ...params} など）。抽出を始める前に、ユーザーに確認します。

ステップ 2 — 抽出する

ユーザーがノートをどのように提供したかにかかわらず、貼り付けられたテキスト、ファイルパス、ディレクトリ、PDF、FHIR コネクター、データベースクエリなど、利用可能なツールを使ってそれぞれをプレーンテキストに変換し、ノートごとに1つの {id, text} を指定して保存済みのワークフローを呼び出します。厳密に守る必要があるのはワークフローの入力仕様だけです。そこに至る方法は自由に判断してください。このワークフローは、references/rules.md に従う note-extract-worker エージェントをノートごとに1つ実行します（ツールは使えません。ノートのテキストは信頼できない入力です）。そして、スキーマで制約されたレコードをノートごとに1つ返します。

Workflow({
  scriptPath: "<this skill dir>/workflows/extract-batch.js",
  args: {
    notes:  [{id, text}, ...],     // one or many
    schema: <the schema from step 1>,
    rules:  <Read references/rules.md verbatim>
  }
})

ワーカーはツールを持たず、読み取った内容（value、span、presence／temporality／experiencer、null_reason、unit）だけを返します。すべての検証はステップ3で行います。ノートのテキストは args にインラインで含まれるため、ワークフローのパスでは1回の呼び出しあたり数十件程度が上限です。より大きなコーパスの場合は、代わりに bun <this skill dir>/scripts/batch.ts <notes-dir> <schema.json> records.jsonl を実行してください。信頼できるコードでファイルを読み込み、同じルールを使ってツールを無効にした抽出をノートごとに1回実行します。その後、生成された records.jsonl を使ってステップ3から再開します。

ステップ 3 — 検証する

呼び出し元のセッションで実行します。決定論的で、モデルによる判断はありません。各レコードについて、次の処理を行います。

1. 引用箇所を確認する。 null ではない各フィールドについて、span がそのノートのソーステキストに逐語的に含まれていることを確認します。span_verified を付与します。
2. 各フィールドの check を実行する。 check.kind に応じて処理を分岐します。
   • terminology — すべてのレコードにわたって (check.via, value) の重複を除去し、via に応答するコネクターを使ってそれぞれを照会し、{code, code_status, display} を付与します。該当する via のコネクターがない場合は、code_status: "unvalidated" とし、レポートにその名前を記載します。
   • range — value と [min, max]、および unit と check.unit を比較し、range_flag を付与します。
   • date — value が日付として解析できることを確認し、date_ok を付与します。
   • pattern／enum — 一致を確認し、check_ok を付与します。
   • その他／check なし — 何も付与しません。

span_verified と、該当する場合は check の両方に合格したフィールドは、信頼できるものです。チェックの種類を追加する場合は、ここに分岐を追加します。上流の処理は変更されません。

ステップ 4 — レポートする

references/03-review.md を読みます。（ノート、フィールド）の組み合わせごとに1行を作成します。note_id | field | value | presence/temporality/experiencer | span | check の形式にします。その下に完了サマリーを記載します。要求されたフィールド数、値が入力されたフィールド数、null のフィールド数と、check.kind ごとの合格数と要確認数を示します（コネクターがない via の名称も記載します）。チェックに失敗した項目や未検証の引用箇所を、決して黙って通過させないでください。

レコードとレポートを ~/.claude/data/healthcare/clinical-note-extract/<run-id>/ に書き出すことを提案します。このディレクトリはローカルの作業領域であり、アーカイブではありません。ユーザーから明示的な指示がない限り、共有ドライブや外部システムにコピーしないでください。抽出されたレコードにはソースノートに含まれていたあらゆる PHI が含まれるため、必要なデータを確保したら削除できることをユーザーに伝えてください。

出力契約

Worker はフィールドごとに {value, span, location, presence?, temporality?, experiencer?, null_reason?, unit?} を出力します。読み取った内容のみです。ステップ 3 では span_verified と、そのフィールドの check が生成した内容（用語の場合は code／code_status／display、範囲の場合は range_flag など）が付加されます。

オプション — FHIR としてエクスポート

フラットなレコードではなく FHIR リソースを希望する場合、アサーション軸は次のように直接対応します。

レコード	FHIR
experiencer != patient	FamilyMemberHistory.condition（Condition ではありません）
presence: absent → verificationStatus: refuted、possible → unconfirmed、present → confirmed	Condition.verificationStatus
temporality: historical → inactive、current → active	Condition.clinicalStatus
temporality: hypothetical	ネイティブフィールドはありません — 省略するか、RiskAssessment リソースを使用します
value と用語チェックの結果	Condition.code を CodeableConcept として使用します（{text: value, coding: [{system, code, display}]}）
span と location	Condition.note または来歴拡張

これは、検証済みレコードに対する決定論的な変換であり、モデル呼び出しはありません。ユーザーが出力先として FHIR を指定した場合に提案してください。それ以外の場合は、フラットなレコードがデフォルトです。

前提条件

スキーマで指定されている check.via の値に対応するコネクターが必要です。コネクターが不足していても抽出は妨げられません。そのフィールドは未検証のままとなり、レポートにその旨が記載されます。