debug-specs

デバッグ仕様

まずルールを読み込んでください。 .plain ファイルを読む、編集する、または書き込む前に、load-plain-reference スキルを実行し、そこから案内されるルールファイルを読んでください。この会話ですでに load-plain-reference が実行されている場合に限り、これを省略できます。

使用するタイミング

• 実行中のアプリケーションでバグが確認された場合（表示、動作、クラッシュ、パフォーマンス）。
• 適合性テストまたは単体テストが失敗している場合。
• 生成されたコードが予期しない動作や誤った動作をする場合。
• ユーザーが特定の機能仕様に問題があるようだと指摘した場合。

基本原則

plain_modules/<module>/code/ および plain_modules/<module>/tests/ 内の生成されたコードは読み取り専用です。診断のための証拠としてのみ存在します。修正はすべて .plain 仕様ファイルにのみ適用します。ワークフローは、観察 → 生成コードを読む → 仕様までたどる → 仕様を修正する、です。

入力

1. モジュール名 — plain_modules/<module_name>/ ディレクトリ（code/ と tests/）および対応する .plain ファイルを特定します。
2. ユーザーの観察内容 — 何が問題ですか？バグの説明、スクリーンショット、テストの失敗、エラーメッセージ、または「正しく動作しない」といった一般的な説明が該当します。
3. 任意：特定の機能仕様 — ユーザーが特定の仕様を疑っている場合は、そこから調査を始めます。そうでなければ、広く調査します。

フェーズ 1 — コンテキストを把握する

1. モジュールの .plain ファイルを読みます。フロントマター、定義、実装要件、テスト要件、すべての機能仕様を確認します。また、import と requires の連鎖、およびモジュールのテスト用 plain ファイルも読みます。
2. ユーザーの観察内容を注意深く読みます。 理解した内容を言い換えて確認します。次の点を特定してください。
   • 期待される動作は何ですか？
   • 実際の動作は何ですか？
   • 表示の問題、ロジックの問題、クラッシュ、またはデータの問題のどれですか？

フェーズ 2 — 生成されたコードを調査する

plain_modules/<module_name>/code/ 内のファイルを読み、レンダラーが生成したものを理解します。生成されたファイルは変更しないでください。

2a. 調査範囲を絞る

ユーザーが特定の仕様または領域を指摘した場合：

• その仕様の動作を実装している生成ファイルを特定します。
• それらのファイルを読み、現在の実装を理解します。

調査範囲が広い場合：

• エントリーポイントから始め、観察されたバグに関連する実行経路をたどります。
• 観察内容を手がかりに範囲を絞ります。UI の問題ならウィジェットやビューを、ロジックの問題ならビジネスロジックやプロバイダーを、データの問題ならモデルやリポジトリを確認します。

2b. 関連する生成コードを読む

関連する各ファイルについて：

1. コードを読み、何をするのかを理解します。
2. 動作を、仕様で定められている内容と比較します。
3. コードが仕様の意図と一致していない箇所など、不一致を記録します。

2c. 適合性テストと単体テストを確認する（関連する場合）

バグがテストの失敗として現れている場合：

1. 失敗したテストを読みます。適合性テストは plain_modules/<module_name>/tests/<func-id>/ 内にあり、それぞれ実装する scenario-id が示されています。単体テストは plain_modules/<module_name>/code/ 内にあります。
2. テストが期待する内容と、実装の動作を把握します。
3. テストの期待内容が正しいか（仕様に一致するか）、それとも誤っているか（仕様に一致しないか）を判断します。

フェーズ 3 — 根本原因を特定する

生成されたコードから仕様にさかのぼって問題を追跡します。考えられる根本原因は6つあります。変更を加える前に、該当する原因を特定してください。

根本原因	症状	修正方法
曖昧な仕様	意図としては正しい仕様ですが、表現が曖昧なため、レンダラーが意図とは異なる解釈をしました。	仕様に明示的な詳細を加え、曖昧さをなくします。
仕様の欠落	望ましい動作がどの仕様にも記載されていません。レンダラーには指針がなく、何もしなかったか、任意の判断をしました。	add-functional-spec スキルを使って、新しい機能仕様を追加します。
仕様の競合	2つの仕様が矛盾しているため、レンダラーが一貫しない動作を生成しています。	resolve-spec-conflict スキルを使います。
誤った仕様	仕様に誤った動作が明示されています。レンダラーは仕様どおりに実装しましたが、仕様自体が誤っています。	正しい動作を記述するよう仕様を書き直します。
誤ったシナリオ	仕様は正しく、コードも仕様に一致していますが、テストプレーンファイルのシナリオが仕様に記載されていない結果を期待しているか、仕様に記載されている結果を見落としています。	add-test-scenarios でシナリオを修正します。
実装要件の欠落	仕様は正しいものの、実装要件にレンダラーが正しいコードを生成するための指針が十分にありません（例：ライブラリ、アーキテクチャ上の制約、プラットフォームの詳細が欠けている）。	add-implementation-requirement スキルを使って、実装要件を追加または更新します。

診断方法

1. 問題のある動作を規定する仕様を読みます。 正しい動作が明確かつ曖昧さなく記述されていますか？
   • 仕様が明確で正しいのにコードが誤っている場合 → 曖昧な仕様（レンダラーが誤って解釈した）または 実装要件の欠落。
   • 仕様にその動作がまったく記載されていない場合 → 仕様の欠落。
   • 仕様に誤った動作が明示されている場合 → 誤った仕様。
2. 競合がないか確認します。 別の仕様がこの動作を上書きしたり、矛盾したりしている可能性はありますか？
   • 同じ概念に関わるすべての機能仕様を読みます。
   • 2つの仕様が相反する場合 → 仕様の競合。
3. シナリオを確認します。 適合性テストまたは受け入れテストが失敗した場合、テスト名にある scenario-id から該当するシナリオを探し、仕様と比較します。
   • シナリオが仕様と矛盾するか、仕様の範囲を超えている場合 → 誤ったシナリオ。
4. 実装要件を確認します。 正しく実装するための指針がレンダラーに不足していますか？
   • 実装要件では、適切なライブラリ、パターン、制約が指定されていますか？
   • プラットフォーム固有またはフレームワーク固有の詳細が欠けている場合 → 実装要件の欠落。

フェーズ 4 — 仕様を修正する

特定した根本原因に応じて修正します。適切なスキルを使ってください。

根本原因	使用するスキル
曖昧な仕様	仕様をその場で編集します。記述行の下に詳細を加えるか、明確になるように言い換えます。
仕様の欠落	add-functional-spec
仕様の競合	resolve-spec-conflict
誤った仕様	仕様をその場で編集し、誤った部分を書き換えます。
誤ったシナリオ	add-test-scenarios
実装要件の欠落	add-implementation-requirement

修正ガイドライン

• 変更は最小限にします。 観察されたバグの修正に必要な箇所のみ変更します。無関係な仕様の書き換えは避けてください。
• 時系列順を維持します。 新しい仕様を追加する場合は、既存の仕様との正しい順序に配置してください。
• 言語に依存しない内容にします。 機能仕様では実装方法ではなく動作を記述します。プラットフォーム固有のガイダンスは実装要件に記載してください。
• 200 LOC の制限を守ります。 修正によって仕様が複雑になりすぎる場合は、break-down-func-spec を使って分割してください。
• テストのプレーンファイルとの整合性を保ちます。 機能仕様を変更した後、そのシナリオが仕様に沿ったままであることを確認するため、add-test-scenarios を実行してください。
• 新たな競合がないか確認します。 編集後、編集した仕様と同じ概念に関係する既存の仕様をすべて指定して analyze-func-specs を一度実行し、修正によって他の仕様と競合しないことを確認してください。バッチ分析では、競合する組み合わせが1回の実行ですべて報告されます。それぞれの競合を resolve-spec-conflict で解決してください。

フェーズ 5 — 検証と報告

1. 変更した .plain ファイルを全文再確認し、正しいことを確かめます。
2. 調査結果をユーザーに報告します。
   • 観察された内容（バグ）
   • 生成されたコードで起きていたこと（コード上の症状）
   • 問題の原因となった仕様
   • 仕様に加えた変更（修正内容）
   • 再レンダリング後に期待される動作
3. 確信が持てない場合は、変更を加える前に診断結果と修正案を提示し、ユーザーに確認します。バグの原因が複数考えられる場合もあります。判断に迷うときは、選択肢を説明してユーザーの判断を仰いでください。

デバッグ戦略

戦略 1：観察に基づく（最も一般的）

ユーザーの観察から始め、コードをたどって仕様を調べます。

User sees bug → Read generated code → Find the responsible code path →
Identify which spec governs that code → Diagnose why the spec produced wrong code →
Fix the spec

戦略 2：仕様に注目する

特定の仕様に原因があるとユーザーが考えている場合は、その仕様と生成されたコードを直接比較します。

User points to spec → Read the spec → Find the generated code that implements it →
Compare spec intent vs. code behavior → Diagnose the gap → Fix the spec

戦略 3：テスト失敗に基づく

テストが失敗している場合は、そのテストを調査の出発点にします。

Read failing test → Understand what it expects → Read the implementation →
Determine if the test or the implementation is wrong → Trace back to the spec →
Fix the spec (or the test reqs / the scenario in the test plain file if the test itself is wrong)

戦略 4：差分を調べる

新しい仕様を追加した後にバグが発生した場合は、追加前と追加後を比較します。

Identify the newly added spec → Read the specs it might conflict with →
Check if the new spec introduced the bug → Use resolve-spec-conflict or
revise the new spec

よくある落とし穴

仕様ではなくコードを修正する

plain_modules/<module>/code/ または plain_modules/<module>/tests/ 内のファイルは変更しないでください。コード上の修正が明らかでも、再レンダリング後も反映されるように、変更は .plain ファイルに加える必要があります。

根本原因ではなく症状に対処する

ユーザーが「ボタンの位置が違う」と言った場合、位置に関する詳細を追加するだけではいけません。レンダラーがその位置に配置した理由を調べてください。根本原因は、レイアウト仕様の欠落、画面の説明の曖昧さ、別の仕様との競合かもしれません。

修正内容を過剰に細かく指定する

機能仕様に実装の詳細（特定のピクセル値、ウィジェット名、CSS プロパティなど）を加えすぎると、変更に弱くなります。動作レベルの修正を優先してください。プラットフォーム固有のガイダンスには実装要件を使います。

波及効果を無視する

仕様の修正は、同じ概念を参照する他の仕様にも影響する場合があります。変更後は必ず、関連する仕様に競合がないか確認してください。

検証チェックリスト

• ユーザーの観察内容を明確に把握している（期待する動作と実際の動作）
• 現在の実装を理解するために、生成されたコードを確認している
• 根本原因を特定している（曖昧／欠落／競合／誤り／誤ったシナリオ／実装要件の欠落）
• 修正は .plain ファイルのみに適用している — 生成されたコードは変更していない
• 修正は最小限で、観察されたバグに的を絞っている
• 修正によって既存の仕様との新たな競合が生じていない
• 変更した仕様は 200 LOC の制限を守っている
• 変更した仕様は言語に依存しない内容になっている
• 時系列順を維持している
• add-test-scenarios を使って、変更した各機能のテストプレーンファイルを最新の状態にしている
• 調査結果と修正内容をユーザーに報告している