KPI 計算機
1つ以上のCSV/TSVファイルと短い指示を、検証済みのKPIセットに変換します。各KPIは値、単位、計算式、意味、根拠ラベルを持ちます。固定されたフィールドリストはありません。KPIはデータと指示が記述する内容に合わせて設計されます。データの横に添付された論文、レポート、過去の結果は、その出典情報とともにユーザーのデータに適用されたKPIを提供します。
以下、<skill_dir>はこのファイルが含まれるフォルダを意味します。スクリプトはpython <skill_dir>/scripts/<name>.pyのように、ワークフォルダ（「出力先」を参照）から実行し、データファイルは絶対パスで渡します。
pythonが見つからない場合（またはMicrosoftストアが開く場合）、Windowsではpy -3、それ以外ではpython3を以下のすべてのコマンドで使用します。開始時にpython --versionで一度確認してください。
厳格なルール
- すべての数値は、ファイルに対して実行されたコードから得られます。 決して値を推定したり、目視で丸めたり、
results.jsonにない値を文章で述べたりしないでください。 - 除外されたKPIは決して計算されず、「あなたのリクエストにより除外」という1行以外のどこにも表示されません。
- すべての仮定は、「私が理解したこと」セクション（パターン、役割、単位、補間、タイムゾーン、日/月の順序、使用されたデフォルト値）に記載されます。
- 1回の実行につき、最大1つの質問のみ許可されます。 そして、誤った推測が結果を変える場合に限ります（
references/role-mapping.md、「いつ質問するか」を参照）。それ以外の場合は、採用した読み取り値を述べて処理を進めます。 - すべてのKPIは、プリミティブから構築された仕様であり、
kpi_specs.jsonに保存されます。 各KPIにはbasis: established（その分野で標準）またはderived（第一原理から構築）のラベルが付けられます。 - 期間にわたる比率は、比率の平均ではなく、合計の比率です。 ただし、KPIが別の定義を持っている場合を除きます。
- 不規則な時間は実時間です。 行を時間ステップとしてカウントしないでください。タイムスタンプを積分し、各列の補間を使用して平均を計算します。
- 検証の失敗は、一度だけ再チェックされます（解析ノート→マッピング→仕様）。その後、警告とともに報告され、隠されることはありません。
- 分野知識はMarkdownのみに記述されます。 スクリプトに分野固有のロジックを追加しないでください。
- 参考文献からの値は引用です。 論文や過去の結果で報告された数値は、仕様の
reference.reportedにのみ格納されます。これらは計算への入力として使用されることはなく、ユーザーの結果として提示されることもありません。
出力先
これをステップ1で決定し、request.json → output_dirに記録します。
| 状況 | ワークフォルダ（すべてのJSONファイル、スクリプトのカレントディレクトリ） | 成果物 |
|---|---|---|
ユーザーがフォルダ名を指定した場合（「結果をD:/reports/line3に保存して」） | そのフォルダ（作成する） | 同じフォルダ |
Claudeアプリ（claude.ai / デスクトップチャット、/mnt/user-data/outputs/が存在する場合） | カレントディレクトリ | /mnt/user-data/outputs/にコピー：ダウンロード可能なファイルとして表示されます |
| Claude Code、フォルダ指定なし | カレントディレクトリのkpi_output/ | 同じフォルダ |
成果物はreport.md、kpi_results.csv、kpi_run.py、および生成された場合にはkpi_chart.png、kpi_adhoc.py、提供されるフィールドパックです。作業ファイル（request.json、profile.json、mapping.json、kpi_specs.json、results.json）は監査のためにワークフォルダに残り、要求された場合のみ共有されます。
成果物をユーザーが任意の場所に保存できるように渡します：
- Claudeアプリ：ダウンロード可能なファイルに加えて、完成したレポートをMarkdownドキュメントのアーティファクトとして表示し、読み取り、コピー、または単独でダウンロードできるようにします。
- Claude Code：各成果物をそのパスへのリンクとしてリストします。ホストがユーザーにファイルを送信するためのツールを提供している場合（デスクトップアプリのファイルカードなど）、それを通しても成果物を送信します。
- ユーザーが要求しない限り、ワークフォルダと成果物の配置場所の外に書き込まないでください。
後でkpi_run.pyを再実行するには、入力ファイルと一緒にフォルダに入れてください。
まずスクリプト、アドホックはフォールバックとしてのみ
常に以下のスクリプトを実行してください。独自のpandasコードを書くのは以下の場合のみです：
- スクリプトが、
profile.json、mapping.json、または仕様を修正しても修正できないエラーで終了した場合（例：profile_csv.pyが解析できない場合）、または - KPIがプリミティブや式でカバーできない操作を必要とする場合（
check_spec.pyがunknown_opを報告する場合）。
その場合は：
- コードを作業ディレクトリに
kpi_adhoc.pyとして配置し、profile.json（またはscripts/lib/io.pyのload）の解析設定でデータをロードし、単独で実行可能に保ちます。 - 各アドホックKPIを
run_specs.pyがファイルを書き込んだ後、results.json → kpisに、schemas/results.schema.jsonのすべてのフィールドと`