spreadsheets

スプレッドシート

厳密な値、最小限の差分、受信者の範囲に限定したデータ処理、アトミックな書き込み、構造検証により、表形式データを扱います。

不変条件

1. 精度が重要な金額は文字列として保持し、計算には decimal.Decimal または DuckDB の DECIMAL(38, 18) を使用します。二進浮動小数点数は使用しません。
2. 指定された行、列、数式、書式のみを変更します。既存ファイルの規約は、プロジェクト内の標準設定より優先されます。
3. 新しく作成するテキスト形式の表には、TSV、BOM なしの UTF-8、LF、末尾の改行 1 つ、小文字の snake_case のヘッダー、ISO 日付、. 小数点、- の null 表記を優先します。
4. 形式不明のテキスト形式の表は、BOM を許容する UTF-8 で読み込みます。BOM は書き込みません。
5. 同じディレクトリ内の一時ファイルを介して、ファイルをアトミックに上書きします。検証後、対象ファイルに置き換えます。
6. =, +, @ で始まる外部セルはエスケープします。単独の - による null は対象外です。信頼できる作成元データの数式プレフィックス付きセルは観測情報であり、インジェクションの証拠ではありません。
7. 取引、銀行、取引所、税務のデータはユーザー所有として扱います。内部エージェントレポートで重要な場合は、非加工のサンプルを使用します。公開や第三者への開示の場合、またはユーザーから求められた場合は、--redact-samples を使用します。

事実に基づくプロファイリング

この SKILL.md を基準にヘルパーのパスを解決します。変換ツールを選ぶ前に、形式不明のデータをプロファイリングします。

uv run "<skill-dir>/scripts/profile.py" <file>

JSON 出力の schema_version は 2 です。構造上の事実、ヘッダーの品質、qsv が利用可能な場合はカーディナリティや統計、頻度に関する事実、数式プレフィックス付きセル、ブックのメタデータ、ローカルツールの利用可否が報告されます。ツールの推奨は含まれず、一意性から識別子を推測することもありません。要求された変換、データの来歴、出力形式、保持要件に基づいてツールを選択してください。

--external-data は、セルが外部またはその他の信頼できないソースに由来し、数式に対応したコンシューマーに書き込まれる場合にのみ使用します。このフラグを指定すると、数式プレフィックス付きセルが status に影響します。指定しない場合、=SUM(...) などの正当な数式は事実の観測情報として扱われ、プロファイルは失敗しません。

ツールの選択

必要な処理	ツール
高速な構造プレビュー／検証	uv run "<skill-dir>/scripts/peek.py" <file>
ローカルデータの事実に基づく品質プロファイル	uv run "<skill-dir>/scripts/profile.py" <file>
件数、統計、頻度、選択、重複排除	qsv
結合、ピボット、集計、変換	all_varchar = true を指定した DuckDB
厳密なカスタム変換	uv run の Python、標準ライブラリ csv、decimal.Decimal
新しいテキスト形式の表、または意図的なスキーマ変更	まず references/text-table-design.md を読む
.xlsx／.xlsm の入力または出力	まず references/xlsx.md を読む
厳密な変換／検証のレシピ	必要な場合に限り references/recipes.md を読む

サポートされている場合は qsv --cache-threshold 0 を優先します。qsv の標準出力を TSV のままにする必要がある場合は、-o out.tsv を使用します。それ以外の場合、標準出力は CSV が既定です。

ワークフロー

1. 新しいテキストテーブルを作成する場合、または意図的にスキーマを変更する場合は、references/text-table-design.md を読み、想定するテーブルインターフェースと移行範囲を記録します。
2. peek.py で調査します。カーディナリティ、数式のプレフィックス、メタデータ、または利用可能なツールが重要な場合は、profile.py を追加します。形状を変更しない編集では、peek JSON を保存します。行またはスキーマを意図的に変更する場合は、想定する列数と不変条件を記録します。
3. 数式のプレフィックスが付いたセルが危険かどうかを、由来と出力コンテキストに基づいて判断します。値と書式を保持できる最小限のツールを選びます。必要でない限り pandas は使用しません。使用する場合は、すべての列を文字列として読み込みます。
4. 変換をアトミックに適用します。正当な重複行を含む冪等な追加には、集合による重複排除ではなく、マルチセット差分を使用します。
5. 検証します。
   • 形状が変わらない場合：peek.py --strict --expect-like <before-report>。
   • 形状が変わる場合：peek.py --strict --expect-columns <n> に、タスク固有の件数やキーを加えます。
   • 作成した社内 TSV：--house を追加します。
   • 数式：uv run "<skill-dir>/scripts/recalc.py" <file.xlsx> を実行し、成功を必須とします。
6. パス、行数・列数への影響、検証結果、保持できなかったワークブックの機能を報告します。

人間向けの出力では、書き込みと必須の検証が完了した後に限り、先頭に ### 📊 Spreadsheet — ✅ updated を記載します。読み取り専用の場合は ### 📊 Spreadsheet — 🔎 inspected, no files written を先頭に記載します。必須の検証に失敗した場合は、### 📊 Spreadsheet — ⛔ not deliverable を使用します。プロファイル JSON は報告に実質的な裏付けとなる場合に限り含め、JSON、セル、ヘッダー、数式、パス、コマンド、診断情報には装飾を加えないでください。

生成された財務成果物

生成された財務テーブルとレポートは出力として扱います。編集前に、それらの元となる入力と、プロジェクトが提供する検証および再生成コマンドを特定します。編集するのはソースのみとし、検証後に影響を受ける出力を再生成します。生成されたテーブルやレポートを手作業で編集してはいけません。財務出力は件数とファイル参照にとどめます。ただし、生の行データがタスクの実行に実質的な裏付けとなる場合、または要求された場合は除きます。エージェントのワークスペース外に財務データを送信する前に、外部開示の審査を行います。

完了には、要求された成果物、意図した差分、該当する場合はアトミックな置換、ならびに構造面とドメイン面の検証証拠が必要です。新規または変更されたテキストテーブルのスキーマには、定義済みのテーブルインターフェースに加えて、影響を受けるプロデューサー、コンシューマー、既存の行、生成物、バリデーターをすべて移行することも必要です。