# A35_トラブルシューティングガイド

統合された執筆支援システムを利用する際に遭遇しやすい問題の症状・原因・対処をまとめました。まずは各項目の「チェックリスト」を順に確認してください。

---

## 1. セットアップ・実行環境

- 症状: `noveler` コマンドが見つからない
  - 原因: グローバルコマンド未インストール
  - 対処: `python scripts/install_global_command.py` を実行

- 症状: 依存関係エラー（ruff/mypy/pytestが動作しない）
  - 原因: 開発ツール未導入または仮想環境未有効化
  - 対処: `scripts/setup_dev.sh` を実行 → その後 `source .venv/bin/activate`

- 症状: Windows/WSLでパスが不正
  - 原因: プラットフォーム固有パス設定の不一致
  - 対処: `config/novel_config.yaml` の `platform_paths.*.default_project_root` を環境に合わせて確認・更新

---

## 2. プロジェクト・ファイル関連

- 症状: 話別プロットが読み込まれない
  - 原因: 期待ファイル名と不一致（例: `第001話_*.yaml`）
  - 対処: `20_プロット/話別プロット/` 直下に `第NNN話_タイトル.yaml` を配置

- 症状: `novel create` 後の構成が不足
  - 原因: 初期化時にフォルダ作成やテンプレート生成が失敗
  - 対処: コマンド出力ログを確認。権限と空き容量を確認し再実行

---

## 3. 品質チェック・LLM連携

- 症状: `novel check` の結果が想定より厳しい/甘い
  - 原因: 実行モードや閾値の設定差異
  - 対処: `defaults.quality_check.mode` と `defaults.plot_adherence.mode/threshold_band` を確認

- 症状: プロット準拠のLLM補助が動作しない（使われない）
  - 原因: `mode: fast` または 閾値帯外（`threshold_band`）
  - 対処: `defaults.plot_adherence.mode` を `gated/strict` に変更、必要なら `threshold_band` を調整

- 症状: LLM助言の信頼性に不安（根拠が弱い）
  - 原因: 抽出された `evidence` の本文一致率が低い
  - 対処: `defaults.plot_adherence.evidence.min_verified_ratio` を調整（例: 0.6→0.8）

---

## 4. キャッシュ・パフォーマンス

- 症状: 同じ原稿で繰り返し時間がかかる
  - 原因: LLM評価キャッシュが無効
  - 対処: `defaults.plot_adherence.cache.enabled: true` を確認。`.noveler/checks/cache/plot_adherence/` にキャッシュ生成を確認

- 症状: キャッシュが古い/更新されない
  - 原因: 設定指紋・本文・話数で生成したハッシュが同一
  - 対処: 設定変更後に再実行。不要なら該当キャッシュ（`EP{episode}_{hash}.json`）を削除

---

## 5. CI/品質ゲート

- 症状: CIでruffやmypyが失敗
  - 原因: ルールに未対応のコードが混入
  - 対処: ローカルで `ruff check .` / `mypy .` を実行し、指摘箇所を修正

- 症状: pytestが落ちる
  - 原因: 仕様変更に伴うテスト更新漏れや環境差
  - 対処: `pytest -q` 実行で失敗テストを確認。差分仕様はテスト更新方針に従い修正

---

## 6. 参考ガイド

- A31_新システム利用ガイド.md（クイックスタート・典型フロー）
- A32_執筆コマンドガイド.md（CLI操作・詳細）
- A33_執筆品質管理チェック.md（品質メトリクス・ゲート）

