回路テスト失敗時のデバッグ手順

このスキルは、レッドストーン回路の自動テストが失敗した際に、原因を切り分けて局所修正するための標準手順です。 本質デバッグは最大5回まで です。5回目でも不合格なら、即座に失敗報告を行ってください。 フレームワーク/DSL/構文/配置順序トラップの修正は試行回数に含めません（trap修正で本質5回を枯渇させない）。

---

トラップ / 本質バグの切り分え（最初に実施）

テスト失敗時、まず 「フレームワーク/DSL/配置順序のトラップ」 か 「本質的な回路バグ」 かを切り分ける。trapなら設定を直すだけで解決し、本質バグなら回路構造を見直す。trapで試行を消費するのは最も無駄な失敗パターン。

詳細は .agents/skills/tool_pitfalls/SKILL.md の「トラップ/本質バグの切り分えフロー」を参照。切り分えチャート:

1. エラーメッセージの確認: 'list' object has no attribute ... 等の Python エラー → フェーズ配列誤り（trap）。
2. 配置後の get_blocks で全体確認: レバーが存在しない / 空中に浮いている → フェーズ順序トラップ。
3. リピーターがOFFのまま: BUD-lock（フェーズ分離不足）または動的状態書き込み（trap）。
4. 操作が効いていない: 同期ズレ。wait_ticks を増やして再確認（trap）。
5. アナログ計算が壊れる: 配線長。アナログ経路を 5〜8 ブロック以内に（trap）。
6. 信号が逆流する: facing 誤り。connects の src/dst を確認（trap）。
7. 上記いずれでもない: 本質的な回路バグ。以下のデバッグ手順へ進む。

trapは tool_pitfalls の推奨チェックリストで事前排除を推奨。本質バグと思っても、まずtrap可能性を潰してから本質デバッグに入ること。

---

プローブ時系列の活用（推奨）

CircuitTest.probe(name, pos) を使うと、1回の test 呼び出しで複数の観測点をまとめて取得できる。結果の details[].probes に [{name, pos, block, state}] の時系列として同梱される。

5回制限を本質デバッグに全振りするため、テストコード内で積極的にプローブを仕込み、1回の test で失敗箇所とその手前の複数観測点を同時に取得する。

async def test_full(self):
    await self.interact_block([10, 65, 10], target_state={"powered": "true"})
    await self.wait_ticks(4)
    # 1回の test で複数観測点を取得
    await self.probe("in", [11, 64, 10])
    await self.probe("ha1_out", [15, 64, 10])
    await self.probe("ha2_out", [20, 64, 10])
    await self.probe("carry", [22, 64, 10])
    await self.assert_block(25, 64, 10, block="minecraft:redstone_lamp", state={"lit": "true"})
    # 失敗時でも details に全プローブの時系列が入る → get_blocks 往復を削減

プローブ時系列があれば、失敗時に「どの観測点までは期待通りで、どこから途切れたか」が1回の test で特定できる。get_blocks の追加往復や test の追加実行を大幅に削減できる。

---

基本姿勢

1. 推測で結果を報告しない: MCPツールの挙動がバグを示した場合は、直ちに作業を中断しユーザーに報告。
2. 生データを確認する: 「たぶん」「おそらく」ではなく、get_blocks 等で実際のブロック状態を確認する。
3. 局所修正: 問題のあるブロックのみを修正。安易な全体リセットは禁止。
4. 段階的修正:
   • 1〜2回目の修正は、問題のある1〜3ブロック程度の最小変更に限定する。
   • 3回目以降、最小変更で解決しない場合は、モジュール構造の見直しなど、より大きな変更も許可される。
   • 大きな変更を行う前には、必ず現在の配置状態を保存（バックアップJSONの作成）する。
5. 悪化検知とロールバック: 修正後のテスト結果が前回より悪化した場合（合格数が減少、または新たな失敗が発生）は、直前の配置状態にロールバックする。ロールバックは修正試行回数にカウントしない。
6. 本質デバッグ5回で止める: 5回の新規修正試行後も不合格なら、それ以上の修正・配置・テストを禁止。trap修正は試行に含めない。
7. dry-run義務: 本テスト実行前には必ずdry-run（配置後 get_blocks で整合確認）を行い、trapを事前排除する。

デバッグ手順

ステップ1: 失敗箇所と期待値を正確に把握

• テスト結果から、どのアサーションが失敗したかを特定する。
• 期待値と実際値を明確に書き出す。
  • 例: 期待 minecraft:redstone_lamp lit=true、実際 lit=false
• 失敗箇所の座標を記録する。

ステップ2: 失敗箇所周辺のブロック状態を取得

• まず format="grid" で get_blocks ツールを実行し、失敗箇所周辺の全体像（配置構造）を把握する。
  • 推奨範囲: 失敗箇所を中心に前後左右上下2〜3ブロック以上。
• 次に format="json" （デフォルト）で同じ範囲を取得し、信号強度（power）、向き（facing）、遅延（delay）などの詳細な状態を確認する。
• 必要に応じて count と interval を使い、信号変化のタイミングを追跡する。

ステップ3: 入力側から信号を追跡する

• 出力側から入力側へ向かって、信号がどこで途切れたかを特定する。
• 確認ポイント:
  • 入力レバー/ボタンの powered 状態
  • レッドストーンダストの power と接続状態 (north/south/east/west)
  • リピーターの powered, delay, facing
  • コンパレーターの powered, mode, facing
  • オブザーバーの powered, facing
  • トーチの lit
  • ピストンの extended

ステップ4: プローブを活用する

• 設計時に記録した中間プローブ（リピーター、コンパレーター、接続ポイント等）を参考にする。
• プローブの状態を get_blocks で確認し、期待通りの信号が届いているかチェックする。
• 必要に応じて、新たに一時的なプローブ（ランプやダスト）を置いて信号を可視化する。

ステップ5: 向き・接続・更新順序を確認

• repeater, comparator, observer は connects を使って正しく向いているか確認。
• レッドストーンダストが意図した方向に接続しているか確認。
• ピストン系回路では準接続 (QC) やブロック更新順序の影響を疑う。
• タイミングがシビアな場合は、リピーターの遅延を調整する。

ステップ6: 入力を手動で再現する

• interact_block ツールでレバー/ボタンを操作し、回路の反応を直接確認する。
• ボタンの場合は、パルス時間（石系: 1.0秒、木系: 1.5秒）を考慮する。
• 必要に応じて get_blocks と interact_block を組み合わせて、複数ステップの動作を追跡する。

ステップ7: 局所修正

• 原因が判明したら、最小限のブロックのみを修正する。
• 修正例:
  • 向きが間違っている connects の from/to を修正
  • 遅延が不足しているリピーターの delay を増やす
  • 接続が切れているダストを追加
  • 意図しないQCの影響を受けているブロックを移動
• 修正後はクリーンアップ→配置→テストのサイクルを再実行する。

ステップ8: 5回目で失敗したら停止

• 5回目の試行後も不合格なら、即座に final_status: failure を報告。
• 報告内容:
  • 失敗したテストケース
  • 最終的に確認したブロック状態
  • 推定される原因
  • 試行した修正内容

失敗パターン別の診断ガイド

テストが失敗した場合、まず失敗パターンを分類し、対応するプローブを確認してください。

失敗パターン	確認すべきプローブ	標準的な修正
全入力パターンで出力が変わらない	入力レバー/ボタンの powered、最初の redstone_wire の power	入力機器が動作しているか、connects/attaches の接続先が正しいか確認
特定の入力パターンのみ失敗	該当入力に関わる中間ゲートの出力、分岐点の power	その入力だけに関わる論理ゲート（AND/OR/XOR）の接続や向きを修正
出力が遅れて変化する	経路上の repeater の delay、各段の redstone_wire の power の遷移タイミング	delay を調整、または追加のリピーターで遅延を明示的に確保
出力が意図と逆	redstone_torch の lit、comparator の mode	トーチの入力を反転、コンパレーターの mode（compare/subtract）を確認
一部のビットだけ失敗（加算器など）	該当ビットのキャリー伝播経路、キャリー入力側の power	キャリーの入力元から出力先までの connects と repeater の向きを確認
信号が混線している	隣接する redstone_wire の接続状態 (north/south/east/west)	配線間に不透過ブロックを挿入、または1〜2ブロック以上の隙間を確保
ピストンが動かない	ピストンの extended、準接続範囲のブロック更新、電源側の power	QCの影響を排除、不動ブロックを確認、更新を与えるブロックを追加
ボタン/レバーの操作後、すぐに元に戻る	入力機器の powered、接続先の redstone_wire の power	ボタンの自動リセット挙動を考慮、レバーに置き換えや待機時間の調整

よくある原因と対処法

症状	よくある原因	対処法
出力が全く変わらない	入力レバー/ボタンが動作していない、配線が途切れている	入力状態を確認し、配線の接続を確認
出力が遅れて変化する	リピーター遅延が不足、ブロック更新順序の影響	遅延を調整、リピーターで明示的な遅延を挿入
出力が意図と逆	トーチやコンパレーターのmodeが逆	lit や mode を確認し修正
ピストンが動かない	準接続の影響、不動ブロック、更新が届いていない	QCの影響範囲を確認、更新を与えるブロックを追加
信号が混線している	配線間隔が近すぎる、強動力が漏洩	1〜2ブロック以上の隙間を空ける、不透過ブロックで遮断

ツールの組み合わせ例

1. interact_block でレバーをON
2. wait_ticks(4) または wait_ms(200)
3. get_blocks で対象範囲を取得
4. 取得結果を分析
5. 必要に応じて place_blocks で局所修正

注意

• デバッグ中も knowledges/ 内のファイルは読み込まない。
• ファイルの書き込みは knowledges/ またはセッションごとの一時ディレクトリのみ。
• 推測で原因を決めつけず、必ず get_blocks 等のツールで確認すること。