bid-leveling

入札レベル調整

建設入札の明細項目を UniFormat II の見出しに対応付けて比較し、レベル調整用のスプレッドシートと簡潔な分析レポートの PDF を作成します。

単一の書類と複数の書類

このスキルでは、単一入札の分析と複数入札の比較の両方に対応しています。どちらの場合もワークフローは同じですが、1 つの書類のみが提供された場合は、次の点が異なります。

• ステップ 3 を省略（スコープの重複評価）— 比較対象がありません
• 推奨事項なし — analysis.json から recommendations と overlap_comparison を完全に省略します。PDF に推奨事項のセクションは表示されません。
• スコープ重複マトリックスなし — analysis.json から scope_overlap を省略します。PDF の 1 ページ目には、プロジェクト情報と入札サマリーテーブルのみが表示されます。
• スプレッドシートと PDF は作成します — スプレッドシートには、単一の入札者の費用を UniFormat に分類して表示します。PDF には、入札の契約条件、スコープ、資格要件、除外事項を詳しく記載します。

これは、追加の入札が届く前に、単一の提案書を分析し、構成を UniFormat のカテゴリに分類して、その条件を記録しておきたい場合に便利です。

ワークフロー

1. プロジェクト情報と出力形式の希望を確認する
2. 各入札書類を読み取り、データを抽出する
3. スコープの重複と比較可能性を評価する（単一の書類の場合は省略）
4. 比較単位を決定する
5. 明細項目を UniFormat コードに割り当て、詳細度を決定する
6. 構造化された JSON データを作成する
7. スプレッドシートを生成する（generate_csv.py を実行）
8. PDF を生成する（generate_pdf.py を実行）

ステップ 1：プロジェクト情報の収集

ユーザーに次の情報を尋ねます。

• プロジェクト名（例：「Smith Residence」）
• 簡単な説明（例：「注文住宅の新築」「キッチンのリフォーム」「配管工事の下請け」）
• 出力形式：CSV または Excel？

ユーザーがすでにこれらの情報を提供している場合は、質問を省略します。

Excel のコンテキスト

ユーザーがすでに Excel ドキュメントで作業している場合（.xlsx ファイルについて言及している、スプレッドシートを参照している、またはスプレッドシートでの作業中である場合）、新しいファイルを作成する代わりに、レベル調整データを既存のブックの新しいシートとして追加します。既存のファイルを generate_csv.py の 3 番目の引数として渡します。

ステップ 2：入札書類の読み取り

提供された各入札書類を読み取ります。書類ごとに、次の内容を抽出します。

• 識別可能な費用明細項目すべて（説明と費用）
• references/bid-analysis-guide.md に記載された契約条件すべて

条件を抽出する際は、元の書類の正確な表現を保持します。

異なるファイル形式の処理

PDF（.pdf） Read ツールで読み取ります。複数ページの PDF はページ範囲を指定して読み取ります（1 回のリクエストにつき最大 20 ページ）。入札書は表形式であることが多いため、明細項目を抽出するときは列の位置関係に十分注意してください。PDF に選択可能なテキストではなく、スキャン画像ベースのコンテンツが含まれている場合は、画像として扱います（下記を参照）。

画像（.png、.jpg、.heic など） Read ツールで読み取ります（マルチモーダル）。画像内に見えるすべてのテキスト、表、明細項目を抽出します。手書きの入札書の写真、メールのスクリーンショット、スキャンした書類などで、画像がよく使われています。以下の点に特に注意してください。

• 手書きの数字 — 判別しにくい数字（例：1 と 7、5 と 6）は、合計金額と照合して確認します
• 一部が見えない場合 — 書類の一部が切れている場合は、不足している箇所をユーザーに尋ねます
• 解像度が低い場合 — 自信を持って読み取れない値があれば、その旨を示します

Excel（.xlsx、.xls、.csv） Read ツールで読み取ります。スプレッドシート形式の入札書は構成が明確なことが多いため、以下を確認します。

• 金額内訳または明細項目のタブ（説明と費用の列）
• 概要／合計のタブまたは行
• 追加の詳細情報が含まれている可能性がある非表示のシートや列
• 小計を計算する名前付き範囲や数式

ユーザーが現在作業中の Excel ファイルに入札書が含まれている場合、これも Excel コンテキストに該当します。出力の処理については、ステップ 1 を参照してください。

Word（.docx、.doc） Read ツールで読み取ります。正式な提案書や契約書には Word 文書がよく使われています。費用情報は次のような場所に記載されていることがあります。

• インラインの表（金額内訳、費用の内訳）
• 金額が埋め込まれた段落のテキスト（「…合計で $45,000…」など）
• 文末に添付された付録や別紙

Word 文書では、契約条項も慎重に抽出してください。免責事項、留保金、支払いスケジュール、保険要件などの条件は、構造化された表ではなく本文に記載されていることがよくあります。

ステップ 3：スコープの重複を評価する

レベリングを行う前に、入札書同士を比較できるか判断します。

• 同じ工種または作業範囲を対象にしていますか？
• UniFormat のレベル 2 のカテゴリを共有していますか？
• 合計金額は互いに比べて妥当な範囲にありますか？

入札書間の重複がごくわずかな場合は、その点を目立つように報告し、直接比較が誤解を招く可能性がある理由を説明します。明確な注意書きを添えたうえで、出力も作成します。

明細項目の詳細モード

明細が記載され、スコープが非常によく似ている入札書（例：窓の一覧、家電パッケージ、パネル化システム、器具一覧）を比較する場合は、次の点を確認します。

• 明細項目の 60% を超える項目に、直接比較できる単価が記載されていますか？
• 入札書間で同等の項目を照合できますか？

該当する場合は、granularity: "line_items" を使用して、同一条件で比較できるよう、実際の要約済み明細項目の説明に分解します。最善を尽くして、入札書間の同等の明細項目を照合した detail_rows 配列を作成します（ステップ 6 を参照）。このモードは、項目を単位レベルで本当に比較できる場合にのみ使用してください。

ステップ 4：比較単位を決定する

単位あたりのコストを比較するうえで、最も意味のある単位を選択します。出力のすべての明細で同じ単位を使用してください。

対象の種類	単位	理由
配管、電気、家電の見積もり	$/fixture	器具の数が自然な数量です
HVAC の見積もり	$/zone	ゾーンが自然な単位です
断熱材、乾式壁、塗装、床材	$/SF（対象範囲の面積）	見積もり対象となる範囲の面積です
架構材の購入、複数の単位が混在する資材の見積もり	$/SF（建物全体）	単一の単位がないため、建物全体の SF を代替として使用します
UniFormat の複数カテゴリにまたがる建物全体／GC の入札	$/SF（建物全体）	対象範囲が広いため、建物の SF が適切です
窓またはドアの明細表	$/unit	窓またはドア 1 つあたりです
屋根工事	$/square（100 SF）または $/SF	屋根工事で使用する単位です

ルール：

• $/lump または $/lumpsum は絶対に使用しないでください — 比較単位として意味がありません。必ずより適切な選択肢があります。
• 可能な場合は、入札内容から単位と数量を導き出します
• 既定の代替単位は常に $/SF（建物の延床面積）です — 対象範囲に固有の単位を特定できない場合に使用します
• 入札で特定の対象面積（例：「タイル 1,200 SF」）が提示されている場合は、建物全体の SF ではなく、その面積を使用します
• 出力のすべての行で単位を統一してください

bid_data.json の unit_of_comparison を設定します：

"unit_of_comparison": {"label": "$/fixture", "quantity": 14}

ステップ 5：UniFormat コードを割り当て、粒度を選択する

references/uniformat_headings.csv を使用して、各明細を UniFormat レベル 3 のコードに対応付けます。

ルール：

• 常に最も具体的なレベル 3 のコードを割り当てます（例：D20 ではなく D2010）— スクリプトが集約を処理します
• 明細が複数のカテゴリにまたがる場合は、主要なカテゴリに割り当てるか、金額が明確であれば分割します
• 一般管理費、間接費、利益、保証金、許可費用は UNCLASSIFIED にします（分類しないでください）

出力の粒度を選択する

対象の種類	粒度	使用する場合
単一業種の下請け工事	"level3"	配管、電気、HVAC — 詳細な比較が有用です
複数業種または一部の対象範囲	"level2"	キッチンの改装、TI — サブグループレベルに集約します
建物全体／GC の入札	"level2"	新築工事 — L2 カテゴリで全体像を把握できます
項目別の見積もりの類似性が高い（重複率 >60%）	"line_items"	窓の明細表、家電一式、器具の一覧

ステップ 6：構造化 JSON を作成する

作業ディレクトリに 2 つの JSON ファイルを作成します。

bid_data.json（スプレッドシート生成用）

{
  "project_name": "Smith Residence",
  "granularity": "level3",
  "unit_of_comparison": {"label": "$/fixture", "quantity": 14},
  "bidders": [
    {
      "name": "ABC Plumbing",
      "line_items": [
        {"description": "Rough-in plumbing fixtures", "uniformat_code": "D2010", "cost": 18500.00}
      ]
    }
  ],
  "detail_rows": []
}

• granularity："level1"、"level2"、"level3"、または "line_items"
• unit_of_comparison：{"label": "$/fixture", "quantity": 14} — 単位あたりのコストを計算するためのラベルと除数です
• detail_rows：granularity = "line_items" の場合にのみ必要です：

"detail_rows": [
  {
    "description": "36-inch farmhouse sink",
    "uniformat_code": "D2010",
    "costs": {"ABC Plumbing": 1200.00, "XYZ Plumbing": 1350.00}
  }
]

analysis.json（PDF 生成用）

すべての詳細フィールドは、段落ではなく簡潔な箇条書き文字列の配列です。

{
  "project_name": "Smith Residence",
  "project_description": "Custom home build",
  "scope_description": "Roofing and exterior scope: roof coverings, exterior walls, drainage",
  "unit_of_comparison": {"label": "$/SF", "quantity": 3200},
  "recommendations": [
    {
      "scope": "Roofing (B3010)",
      "recommended_bidder": "Rolvin Carpentry",
      "rationale": "On overlapping scope (roofing only), Rolvin is $35,000 vs Perry $110,250 — 68% less"
    },
    {
      "scope": "Exterior Walls (B2010), Drainage (D2040)",
      "recommended_bidder": "Rolvin Carpentry",
      "rationale": "Only Rolvin covers these scopes; Perry does not quote exterior walls or drainage"
    }
  ],
  "overlap_comparison": {
    "shared_categories": ["B3010 ROOF COVERINGS"],
    "overlap_totals": {"Perry Verrone LLC": 110250.00, "Rolvin Carpentry Inc": 35000.00},
    "notes": "Perry's total ($110,250) appears lower than Rolvin's ($140,000) but Perry only covers roofing. On the shared scope, Rolvin is 68% cheaper."
  },
  "scope_overlap": [
    {"description": "Roof coverings", "uniformat_code": "B3010", "bidders": {"Perry Verrone LLC": true, "Rolvin Carpentry Inc": true}},
    {"description": "Exterior walls", "uniformat_code": "B2010", "bidders": {"Perry Verrone LLC": false, "Rolvin Carpentry Inc": true}},
    {"description": "Rain water drainage", "uniformat_code": "D2040", "bidders": {"Perry Verrone LLC": false, "Rolvin Carpentry Inc": true}}
  ],
  "bidders": [
    {
      "name": "ABC Plumbing",
      "brief_summary": "Comprehensive bid at $34,300 — fixtures, heater, waste, drainage",
      "total_cost": 34300.00,
      "unit_cost": 2450.00,
      "scope_differences": [
        "Includes rain water drainage (D2040) — XYZ excludes",
        "Water heater $4,500 vs XYZ $5,200 for domestic water"
      ],
      "duration_and_schedule": ["6-8 weeks", "Monthly progress billing, Net 30"],
      "preconditions": ["Framing + rough electrical complete", "Slab on grade poured"],
      "substantial_completion": ["All fixtures operational", "Pressure test passed"],
      "lien_waiver_requirements": ["Conditional with each progress payment", "Unconditional at final"],
      "qualifications": ["CA License #987654 (C-36)", "$2M GL, $1M auto"],
      "exclusions_and_terms": ["Excludes permits/inspections", "10% retainage, released at final"]
    }
  ]
}

スキーマは 2 種類の推奨スタイルに対応しています：

• 単一の推奨：重複率が高い場合は、recommendations に 1 つの項目を使用します
• 対象範囲ごとの推奨：対象範囲が異なる場合は、UniFormat の領域ごとに個別の推奨を作成します

overlap_comparison オブジェクトには、共通カテゴリの同条件で比較可能な小計と、合計額の比較が誤解を招く理由を説明する注記が含まれます。合計額が誤った印象を与える場合に使用します。

対象範囲の重複マトリックス

scope_overlap 配列は、PDF の 1 ページ目にある比較表を生成します。CSV よりも細かい単位で対象範囲を列挙し、各入札者が何を含み、何を含まないかを正確に示します。それぞれに UniFormat コードを付けます。入札ごとの明細のうち、どれが同等かをできる限り判断してください。

推奨のロジック

対象範囲が異なる入札同士の合計額は、絶対に比較しないでください。 入札者が作業範囲を少なくしている場合、合計額が低くても価格が優れているとは限りません。

ステップ 1：重複する範囲と重複しない範囲を特定する

範囲の重複マトリックスを使い、項目を次のように分類します。

• 重複する範囲：両方の入札者がこの範囲を含んでいる（同条件で比較可能）
• 入札者 A のみ：一方の入札者のみがこの範囲を対象としている
• 入札者 B のみ：もう一方の入札者のみがこの範囲を対象としている

ステップ 2：重複する範囲のみを比較する

各入札者の重複範囲のみの小計を計算します。これは、両方の入札者が対象としている UniFormat カテゴリの費用のみを合計したものです。総額ではなく、この金額で入札者を比較します。

例：入札者 A が屋根工事を 110,250 ドルで提示し、入札者 B が屋根工事を 35,000 ドル、外壁工事を 93,333 ドル、排水工事を 11,667 ドルで提示した場合、屋根工事の同条件での比較は 110,250 ドル対 35,000 ドルです。総額は高くても、共通する範囲では入札者 B の方が大幅に安価です。

ステップ 3：範囲を考慮した推奨を行う

• 重複率が高い（項目の 70% 超が共通）：重複する費用の比較、十分さ、契約条件に基づき、単一の推奨を行います
• 部分的な重複：必要に応じて、範囲ごとに個別の推奨を行います（例：「屋根工事では入札者 B が大幅に安価です。入札者 A は外壁工事や排水工事を対象としていません」）
• 重複が最小限（共通する範囲が 30% 未満）：どちらか一方を推奨しないでください。範囲が大きく異なるため直接比較できないことを伝え、それぞれが対象とする範囲を説明します

ステップ 4：独自の範囲を考慮する

一方の入札者が、もう一方には含まれていない範囲を含めている場合は、次の点を明示します。

• 発注者は何を別途調達する必要がありますか？
• 追加の範囲は、より高い総額に見合いますか？

重み付け（重複する範囲について）

1. 同条件での価格 — 重複するカテゴリのみの費用
2. 範囲の網羅性 — 対象範囲が広いほど、別途調達するものが減ります
3. 契約条件の明確さ — 明確な条件、妥当な条件、十分な保険

ステップ 7：スプレッドシートを生成する

CSV：

uv run scripts/generate_csv.py bid_data.json bid_level.csv

新しい Excel ファイル：

uv run scripts/generate_csv.py bid_data.json bid_level.xlsx

既存の Excel ファイルにシートを追加：

uv run scripts/generate_csv.py bid_data.json bid_level.xlsx existing_workbook.xlsx

出力形式はファイル拡張子から判定されます。スクリプトは references/uniformat_headings.csv を自動的に読み込みます。

ステップ 8：PDF を生成する

uv run scripts/generate_pdf.py analysis.json bid_level.pdf

PDF は次のように構成されます。

• 1 ページ目：プロジェクト情報、推奨事項、入札概要表、チェックマーク付きの範囲重複マトリックス
• 2 ページ目以降：入札者ごとの詳細を簡潔な箇条書きで記載（範囲の差異、スケジュール、前提条件、完了条件、リーン放棄書、資格要件、除外事項）

リソース

• references/uniformat_headings.csv — UniFormat II レベル 1／2／3 の見出し階層全体
• references/bid-analysis-guide.md — 入札書類と契約条件の抽出ガイド
• scripts/generate_csv.py — 入札データ JSON からスプレッドシート（CSV または Excel）を生成
• scripts/generate_pdf.py — 分析 JSON から PDF レポートを生成