opt-assess

name	opt-assess
description	受け取ったデータから最適化問題の構造を把握し、仮説を立てる。最も重要なスキル。
user_invocable	true

Skill: opt-assess（問題アセスメント）

/opt-assess [data_path] で実行。

全スキルの中で最も重要。 ここで問題の見立てを間違えると、後の全てが無駄になる。「5分でデータを見て分類する」のではなく、「問題の本質を正しく理解する」ことに時間をかける。

いつ使うか

• クライアントやチームから「これ最適化できる？」とデータを渡された時
• 何を最適化すべきか自体がまだ曖昧な時

---

Opus 4.7 ヒント

このスキルは 読込量が多く判断1回が重い。以下を必ず守る:

• 並列 Read: data/ の全ファイル、該当 reference/hearing_sheet_*.md、関連テンプレ・ガイド、literature_guide.md、spec_template.md を 1 メッセージで一括 Read。1M コンテキストの数 % しか使わない
• 拡張思考は 2 箇所: ① Phase 2.2 の問題分類（複合型の見極め）、② Phase 3.2 の複雑度判定（simple/medium/complex）。判定ミスは後続戦略を狂わせる
• 未知領域の調査は Explore サブエージェント: 「この業界に類似事例があるか」等は subagent_type=Explore に委ねて主スレを汚さない
• 仮定の確信度は明示: 各仮定に confidence: high/medium/low を付ける（後続スキルが参照する）

詳細は reference/opus47_collaboration.md。

---

Phase 1: データの理解（何があるか）

1.1 データの中身を把握する

- 全ファイルを開いて構造を確認（シート数、カラム、行数）
- データ型（数値/文字列/日時/座標）を確認
- 欠損値、外れ値、重複を確認
- IDの体系（何がユニークキーか）を特定

1.2 テーブル間の関係を理解する

よくあるパターン:
  ├── マスタ系: 人、場所、車両、商品 → 「何があるか」
  ├── トランザクション系: 注文、訪問記録、勤務実績 → 「何が起きたか」
  └── 制約系: ルール、上限下限、スケジュール → 「何を守るか」

テーブルが複数ある場合:
  → どのテーブルが何と紐づくかをER図的に整理
  → 結合キーは何か（ID? 日付? 名前?）

1.3 データの品質チェック

□ カラム名は意味がわかるか？（略語や社内用語がないか）
□ 単位は明記されているか？（km? m? 分? 時間?）
□ 日付の形式は統一されているか？
□ カテゴリ値に表記ゆれはないか？（「東京」「東京都」「Tokyo」）
□ 数値の範囲は妥当か？（体重300kgの人がいないか）
□ NULLは「未入力」か「0」か「該当なし」か？

---

Phase 2: 問題の理解（何を解くか）

2.1 依頼者へのヒアリング項目

データだけでは問題は定義できない。以下を確認する。 データに書いていないが問題を解くのに必須な情報が必ずある。

■ 目的（What）
  「何を良くしたいですか？」
    ├── コスト削減？ → 目的関数 = コスト最小化
    ├── 品質向上？ → 目的関数 = 品質スコア最大化
    ├── 公平性？ → 目的関数 = バラつき最小化
    └── 複数ある → 優先順位を確認（「コストと品質どちらが大事？」）

■ 制約（Must）
  「絶対に守らなければならないルールは？」
    ├── 法律・規制 → ハード制約（絶対守る）
    ├── 社内ルール → ハード or ソフト（「破れるか？」を確認）
    ├── 物理的制約 → ハード制約（車に100個しか入らない等）
    └── 慣習 → ソフト制約（「できれば守りたい」レベルか確認）

■ 現状（As-Is）
  「今はどうやっていますか？」
    ├── 手作業 → Before/After比較の基準になる
    ├── Excelで組んでいる → そのロジックが制約のヒントになる
    └── ベテランの勘 → 暗黙知がある（Amazonの事例と同じ）

■ 評価（How to judge）
  「良い結果と悪い結果の違いは？」
    ├── 明確な指標がある → 評価関数に直結
    └── 曖昧 → 仮の評価基準を提案して合意をとる

■ 規模と頻度
  「どれくらいの量を、どれくらいの頻度で？」
    ├── 月1回 → 時間をかけて良い解を出す方針
    ├── 毎日 → 自動化が必要、計算時間の制約あり
    └── リアルタイム → 即応性が最優先、近似解で妥協

2.2 問題の分類（思考回路④ パターン認識）

ヒアリングした内容を既知の問題クラスに当てはめる。 reference/literature_guide.md を参照して、既存の最良手法とベンチマークを確認する。 特に大規模問題や特殊制約がある場合は、同業界の事例論文が制約設計のヒントになる。

決めたいこと（決定変数）は何か？

  「誰を・いつ・何に割り当てるか」
    → スケジューリング / 割当問題
    → ツール: CP-SAT, MIP (Gurobi, OR-Tools)
    → 似た問題: シフト表、時間割、タスク割当

  「どの順番で・どう回るか」
    → 巡回セールスマン問題(TSP) / 配車問題(VRP)
    → ツール: OR-Tools Routing, LKH
    → 似た問題: 配送ルート、営業巡回、集配

  「何を・どこに詰めるか」
    → パッキング / カッティング
    → ツール: ビンパッキングソルバー
    → 似た問題: コンテナ積載、倉庫配置

  「何を選ぶか・いくつ選ぶか」
    → ナップサック / 集合被覆
    → ツール: MIP
    → 似た問題: ポートフォリオ、仕入れ最適化

  「複合型」（↑の複数が混ざっている）
    → まず分解できないか考える（思考回路①）
    → 例: 「誰がどの車でどの順番で」= 割当 + VRP

2.3 見立てを間違えやすいケース

注意1: 「見た目」と「本質」が違う
  依頼: 「配送ルートを最適化したい」
  実は: 「どの荷物をどの車に積むか」が本当の問題（割当問題）
  → ルートはその後の話。割当が決まればルートは自動で決まる場合がある

注意2: 制約と目的関数の取り違え
  依頼: 「コストを◯◯万円以下にしたい」
  これは目的関数？制約？
  → 制約なら「コスト ≤ ◯◯万」→ 予算内で品質最大化
  → 目的関数なら「コスト最小化」→ 品質は制約で下限設定
  → どちらかで解の性質が大きく変わる

注意3: 「最適化」が本当に必要か
  依頼: 「最適なルートを出してほしい」
  実は: ルールベース（「近い順に回る」）で十分かもしれない
  → まず簡単な方法で解いて、その結果を見て判断

注意4: 現場の暗黙知を無視すると失敗する
  数学的に最適でも「このルートは一方通行で走れない」
  「この人とこの人は仲が悪いから同じシフトにできない」
  → データに載っていない制約を必ず聞く

---

Phase 3: 規模と実現性の評価

3.1 問題の規模を見積もる

決定変数の数（概算）:
  スケジューリング: 人数 × 日数 × スロット数
  VRP: 訪問先数² × 車両数（アーク変数）
  パッキング: アイテム数 × 配置候補数

制約の数（概算）:
  「〜以下」「〜以上」「必ず〜」の条件を数える

規模の目安:
  小（~100変数）    → OR-Toolsで瞬殺
  中（~1,000変数）  → OR-Toolsで数秒〜数分
  大（~10,000変数） → 分解が必要
  巨大（100,000+）  → 専用ソルバーやメタヒューリスティクス

3.2 複雑度の判定（重要）

後続の opt-baseline の解法戦略を決める判断。必ず判定して出力すること。

以下の5軸で評価し、総合的に simple / medium / complex のどれかを判定する。

軸1: 変数規模
  ├── <100     → simple
  ├── 100-1000 → medium
  └── >1000    → complex

軸2: ハード制約の数
  ├── ≤5  → simple
  ├── 6-10 → medium
  └── >10  → complex

軸3: 問題タイプ
  ├── 単一問題（スケジューリングのみ、VRPのみ等） → simple
  ├── 単一問題+特殊制約 → medium
  └── 複合問題（スケジューリング+マッチング等）   → complex

軸4: 制約の相互作用
  ├── 制約同士が独立 → simple
  ├── 一部連動       → medium
  └── 強く連動（1つ緩めると他も変わる） → complex

軸5: ドメイン・実績
  ├── 既知パターン（ベンチマーク・事例多数） → simple
  ├── 業界特有の制約あり → medium
  └── 新規・類似事例少ない → complex

総合判定ルール:

• 全軸 simple → simple
• complex が 1つでも → complex
• それ以外 → medium

3.3 既存の解法があるか調べる

□ この問題クラスにOR-Toolsのチュートリアルがあるか？
□ 同じ業界で最適化した論文・事例があるか？
□ 使えるベンチマークデータセットがあるか？
→ あれば大幅にショートカットできる

3.4 仮定を明示する

これが最も重要。 データにない部分は仮の値を置くしかないが、それを明示する。

仮定のリスト:
  - 「移動速度は30km/hと仮定」
  - 「1件あたりの作業時間は10分と仮定」
  - 「需要は一定と仮定（季節変動なし）」

なぜ大事か:
  仮定が間違っていれば結果も間違う。
  仮定を書くと、現場の人が「いやそれは違う、実際はXX」と教えてくれる。
  → これが追加データを引き出す最も効率的な方法。

---

Phase 4: 出力

仕様書（spec.md）の生成

バージョンフォルダ（v1/）内に spec.md を生成すること。 これがこのバージョンの仕様書になる。 テンプレートは reference/spec_template.md を参照。

• 目的・ハード制約・ソフト制約・仮定をここに集約する
• 後続スキル（baseline, improve）はこの仕様書を参照して実行する
• 追加データや制約変更が来たら、新バージョンフォルダ（v2/）を作り、spec.md を複製して更新する

assess レポート

以下のMarkdownをバージョンフォルダ内の reports/assess_report.md に保存すること。 後続スキルが参照する。

## 問題アセスメント

### データの概要
- ファイル: [ファイル名] (N行 × M列, X MB)
- テーブル数: [N個]
- 主なエンティティ: [人/場所/車両/商品/...]
- データ品質: [良好 / 要クリーニング / 要確認事項あり]

### 問題の分類
- 種類: [スケジューリング / VRP / パッキング / 割当 / 複合]
- 規模: [小/中/大] (変数 約X個, 制約 約Y個)
- 類似問題: [XX問題に似ている]
- 使えそうなツール: [OR-Tools XX / Gurobi / カスタム]

### 複雑度評価
- 総合判定: **[simple / medium / complex]**

| 軸 | 評価 | 根拠 |
|----|------|------|
| 変数規模 | [simple/medium/complex] | [変数数] |
| HC数 | [simple/medium/complex] | [HCの数] |
| 問題タイプ | [simple/medium/complex] | [単一/複合] |
| 制約の相互作用 | [simple/medium/complex] | [独立/連動] |
| ドメイン | [simple/medium/complex] | [既知/新規] |

→ **推奨解法戦略**:
- simple: opt-baseline で一発解き（random/greedy/solver の3手法）
- medium: まず一発解き、infeasible なら段階化
- complex: **段階的 baseline 必須**（HC1から1つずつ追加、壁を特定）

### 目的と制約の整理
- 目的関数（最小化/最大化したいもの）:
  1. [主目的]
  2. [副目的]
- ハード制約（必ず守る）:
  1. [制約A: 根拠=法律/物理/ルール]
  2. [制約B]
- ソフト制約（できれば守りたい）:
  1. [制約C]
  2. [制約D]

### 仮説
1. [この問題のボトルネックはたぶんここ]
2. [こういうアプローチが効きそう]
3. [この制約が一番きつそう]

### 仮定（データにないため仮の値を置いたもの）
- [仮定1: XXはYYと仮定。根拠: ZZ]
- [仮定2: ...]
→ **これらの仮定が正しいか確認をお願いします**

### 不足情報（追加依頼が必要）
- [ ] [何が / なぜ必要 / ないとどうなるか]
- [ ] ...

### 確認事項（回答しやすい形式で）

**「教えてください」ではなく「こう理解していますが合っていますか？」の形式で書く。**
回答候補を具体的に提示し、現場の人が選ぶ or 訂正するだけで済むようにする。

#### Q1: [質問タイトル]
[背景: なぜ確認したいか]

現在の理解: **[こう理解しています]**
- [ ] A) [選択肢A]
- [ ] B) [選択肢B]  
- [ ] C) その他（＿＿＿＿）

#### Q2: ...
...

### 次のステップ
→ 確認事項の回答後 /opt-baseline でベースライン構築

---

状態管理

読み込み

• バージョンフォルダ内の .opt_state.yaml が存在すれば読み込み、前回の assess 結果を確認する
• 追加データが来た場合は前バージョンの assess を参照して差分を分析する

書き込み

• 実行完了時にバージョンフォルダ内の .opt_state.yaml の assess セクションを書き込む
• スキーマは reference/state_schema.md を参照

---

トラブルシューティング

データが読めない

症状: Excel ファイルが文字化けする / CSV が読めない
原因と対策:
  ├── 文字コードが Shift_JIS → encoding='shift_jis' or 'cp932' を指定
  ├── Excel の日付がシリアル値 → pd.to_datetime(df['col'], unit='D', origin='1899-12-30')
  ├── Excel にマクロ付き (.xlsm) → openpyxl で読める、xlrd は非対応
  └── CSV の区切りがタブ → sep='\t' を指定

データが大きすぎてメモリ不足

症状: pandas で読み込み時に MemoryError
対策:
  ├── dtype を指定して省メモリ化: pd.read_csv(..., dtype={'col': 'int32'})
  ├── 必要なカラムだけ読む: usecols=['col1', 'col2']
  ├── チャンク読み: pd.read_csv(..., chunksize=10000)
  └── 分析は先頭1000行で行い、全体は後のスキルで処理

問題の分類が難しい

症状: 複数の問題タイプに見える / どれにも当てはまらない
対策:
  ├── 決定変数を先に特定する（「何を決めたいか」が分類の鍵）
  ├── 複合問題なら分解を検討（思考回路①）
  ├── 類似の業界事例がないか調べる
  └── 無理に分類せず、「複合型」として assess を完了し baseline で試す

クライアントがヒアリングに応じてくれない

症状: 「データだけ渡すので最適化してください」と言われる
対策:
  ├── 仮定を明示した中間報告を出す（「XXと仮定しましたが正しいですか？」）
  │   → 仮定が間違っていれば、現場の人が訂正してくれる
  ├── ベースラインの結果を見せる（「現状こうなりますが合ってますか？」）
  └── /opt-request で「これがないとこうなる」を具体的に説明する依頼書を生成