Phase 11

docs/phase11_specification.md

@@ -0,0 +1,56 @@
+# Phase 11 パイロット実験診断仕様
+
+## 目的
+
+Phase 7統合ログとPhase 8解析結果を用い、本実験へ進めるデータ品質かを診断する。新しい認識アルゴリズムではなく、実データに基づく運用・品質・設定改善支援である。
+
+## 入力
+
+- `*_person_analysis_table.csv`
+- `*_session_summary.csv`
+- Phase 8解析ディレクトリ
+- Phase 10品質Issue
+
+顔向き評価不能と「評価可能だが反応なし」を混同しない。`valid_for_voice_analysis=false`を反応なしへ含めない。
+
+## 診断
+
+Prompt/Controlの総数、有効解析人数、反応率、有効音声解析率、not_evaluable率、no_pose_estimated率、条件人数比、セッション品質、camera_position_noteを確認する。
+
+- `ready`: 両条件が目標人数以上で、各品質閾値、人数バランス、カメラ記録を満たす。
+- `needs_minor_adjustment`: 最低人数はあるが目標未達、または条件バランスに軽微な問題がある。
+- `needs_major_adjustment`: 有効率、評価不能率、Pose取得率、カメラ位置記録に重大な問題がある。
+- `insufficient_data`: 条件欠損、最低人数未満、空データ。
+- `error`: 必須列破損等で診断不能。
+
+## 改善提案
+
+ルールを明示し、カメラ位置、顔処理、閾値・response window確認、サンプル数、条件バランス、ログ・プロトコルをhigh/medium/lowで提案する。自動的に設定値を書き換えない。
+
+## セッション比較
+
+セッション単位で有効率、反応率、評価不能率、Pose未推定率、反応時間、カメラ位置メモを集計し、good/caution/poorに分類する。
+
+## 変更履歴
+
+`CalibrationHistory`は変更前後、理由、操作者、関連report IDをUTF-8 BOM CSVへ追記する。同じchange_idは拒否する。
+
+## 出力
+
+- `pilot_diagnostic_report.md`
+- `pilot_diagnostic_metrics.csv`
+- `improvement_recommendations.csv`
+- `session_quality_summary.csv`
+- `calibration_history.csv`
+
+## CLI・GUI
+
+`pilot-diagnostics`, `calibration-add`, `calibration-list`はカメラ、YOLO、MediaPipe、音声を初期化しない。GUI Diagnosticsタブも同じ処理をワーカースレッドで実行する。
+
+## 制約
+
+readyは研究デザインの妥当性を保証しない。少数サンプルの有意差は不安定であり、高い反応率も音声との因果関係を証明しない。照明、通行方向、混雑、カメラ位置、ID switchの影響を別途確認する。
+
+## Phase 12
+
+改善履歴を反映して本実験データを収集し、Prompt/Control双方のセッション数・有効人数を確保し、最終解析と報告へ進む。