fireworks-open-eli5

Fireworks Open ELI5

難解なシステムを、事実に忠実なビジュアルストーリーに変換します。まず持ち運び可能な JSON 仕様を作成し、その後、決定論的で自己完結した HTML の解説を生成します。

譲れない境界

• ビジュアルの仕上がりよりも、エビデンスを優先します。各エビデンス項目に verified、inferred、analogy のいずれかを付けてください。
• アナロジーを実装上の事実のように見せてはいけません。
• 生成されたローカル HTML ファイルは、あくまで generated です。published、アップロード済み、送信済み、または送信先で検証済みではありません。
• ユーザーから明示的な依頼があり、送信先のワークフローで独自に検証されない限り、公開、アップロード、送信、アクセス権の変更を行わないでください。
• レンダリングではネットワーク呼び出しを行いません。引用 URL は読者向けのリンクであり、実行時の依存関係ではありません。オプションのネイティブ Pages アクションでは、バンドルされた同一オリジンのヘルパーを 127.0.0.1 上で呼び出すことのみ可能です。リモートサービスに接続してはいけません。
• ブラウザー内の履歴、お気に入り、注釈は、読者がオプトインするまで無効です。これらは利便性のための状態であり、エビデンスではありません。また、ソース仕様や生成された成果物を変更することはありません。
• 履歴は、そのブラウザーで以前に開かれた同一オリジンの解説として、正確に説明してください。生成されたファイルをすべて列挙すると主張してはいけません。
• PDF のエクスポートでは、ブラウザーの印刷ダイアログを呼び出します。PNG は 1 つのシーンをエクスポートし、PPTX と Pages 互換の DOCX は、スライドまたはページごとに 1 つのシーンをエクスポートします。ネイティブの .pages 出力を許可できるのは、インストール済みの Pages アプリが実際に保存した後に限ります。DOCX の拡張子を .pages に変更してはいけません。生成されたダウンロードはローカルの成果物に限られます。

ワークフロー

1. 読者、質問、言語、そしてストーリー全体を通してたどるものを1つ特定します。リクエスト、パケット、意思決定、イベント、ユーザー操作などが該当します。

2. ストーリーの構成を1つだけ選びます。

   • concept：直感 → 仕組み → 境界。
   • module：入口 → 変換 → 出力／依存関係。
   • tradeoff：共通の目標 → 競合する選択肢 → 結果／判断基準。
   • incident：通常の経路 → 破綻と伝播 → 検出／復旧。

3. 根拠を集めます。リポジトリを扱う場合は、実際のファイルを調べ、ローカルパスを使用します。外部の主張については、利用可能な場合、信頼できる情報源を参照します。不確実性は明示的に記録します。

4. references/spec-contract.mdに従って、バージョン1のJSON仕様を作成します。3～7個のシーン、各シーンに2～6個のノード、完全な真実の階層、トレース、用語集、理解度確認、根拠マップ、必須のモード固有のmodeDataを含めます。重大な影響を伴うノードには、失敗に関する情報を追加します。

5. レンダリングする前に検証します。

   node scripts/validate.mjs path/to/spec.json
   

6. 新しいローカルファイルにレンダリングします。

   node scripts/render.mjs path/to/spec.json path/to/explainer.html
   

   レンダラーは、既存のパスを拒否します。ユーザーが既知の通常ファイルを置き換えることを明示的に希望した場合に限り、--forceを追加します。強制レンダリングではアトミック置換を使用し、シンボリックリンクとファイル以外のパスは引き続き拒否します。

7. 仕様と生成物をまとめて検証します。

   node scripts/validate.mjs path/to/spec.json path/to/explainer.html
   

8. ブラウザーにアクセスできる場合は、ローカル生成物をデスクトップ幅と390px幅で確認します。h1が1つだけであること、ラベルが読みやすいこと、横方向にはみ出さないこと、キーボードフォーカス、独立したタブリスト、全体およびシーン単位の再生、ビューポート追従、実際のエッジと根拠カードの同期、アニメーションの開始／保持／終了フェーズ、失敗レンズ、回答の表示、リモートリソースへのリクエストがゼロであることを確認します。すべてのシーンの根拠カードに、ステータス、簡潔な主要根拠、裏付けの範囲、URLまたは明示的な参照先なしの境界を表示する必要があります。

9. 読者ワークスペースをテストします。モーダルドロワーをマウスとキーボードで開閉し、フォーカスが戻ることを確認します。ライブラリを意図的に有効にし、再読み込み後にお気に入りとプレーンテキストの注釈が保持されることを確認します。また、履歴には実際に開いた同一オリジンの解説ページだけが含まれることを確認します。マークアップ形式に見える注釈を使い、不活性なテキストのままであることを確認します。

10. エクスポートをテストします。印刷用スタイルシート、PNGのシグネチャと寸法、PPTXおよびDOCXのZIPシグネチャと必須のOOXMLパーツ、ならびに自動ダウンロードが抑止された場合のフォールバック用ダウンロードリンクを確認します。シーンの画像に、ステータス、主要根拠、参照元または境界を含む、範囲の明確な根拠フッターが表示されることを目視で確認します。ネイティブのPagesが対象の場合は、scripts/serve.mjsを経由して実行し、.pagesパッケージにIndex/Document.iwaが含まれることを確認してから、Pagesで開き直します。仕様またはテンプレートを変更した場合は、両方のバリデーターを再実行します。

レポートの言語

• 最終的なQA、ステータス、引き継ぎ、生成物のレポートは、明示的な指定がない限り、ユーザーの直近の実質的な依頼の言語で作成します。
• レポートの言語が明示的に指定されている場合は、そちらを優先します。
• spec.languageが制御するのは生成される解説ページのインターフェースのみです。会話のレポート言語は指定しません。
• 複数の言語が使われている会話では、レポート言語を決める際に短い相づちは考慮しません。翻訳によって正確性が損なわれる場合は、コード、コマンド、パス、識別子、正確なエラーメッセージ、ソースのタイトルをそのまま保持します。

言語選択と納品レポートの契約の詳細は、references/reporting.mdを参照してください。

ストーリー構成ルール

• タイトルはカテゴリー名ではなく、具体的な約束を示すものにしてください。
• 要約は1文に収め、各ノードの役割は1つにしてください。
• シーンは3～5個を優先してください。段階を省くと因果関係が歪む場合に限り、6～7個にしてください。
• エッジは関係またはアクションを表します。ラベルには短い動詞を使ってください。
• トレースは、意味のある順序で実在するノード ID をたどる必要があります。
• 影響、目に見える症状、フォールバックが判明している場合に限り、障害データを使用してください。
• シンプルなレイヤーは、技術レイヤーに照らしても正確さを保てるようにしてください。
• 制約は小さな免責事項ではなく、truthLadder.caveat に記載してください。
• 根拠となるシーンまたはノードにソース ID を付けてください。
• 主張に隣接しているというだけの理由で、ソースを引用しないでください。

モードのパターンについては references/story-grammars.md、主張の境界については references/evidence-rules.md を読み、レンダラーのビジュアル言語を変更する前に references/visual-system.md を読んでください。永続化、ナビゲーション、再生、またはエクスポートの動作を変更する前に references/library-and-export.md を読んでください。

品質ゲート

以下をすべて満たす場合にのみ、ローカル成果物として完成です。

• バリデーターが仕様とレンダリング済み HTML の両方に対して ok: true を返す。
• すべての ID と参照が解決される。
• 必須のインタラクティブセクションすべてに内容がある。
• 選択したストーリーモードが、それぞれのセマンティックコントラクトを満たす。
• HTML が決定論的で、仕様の SHA-256 メタタグを含んでいる。
• 成果物が提供された仕様とバイト単位で一致し、信頼できる CSP ハッシュを使用している。
• 成果物に外部リソース、安全でないランタイム API、リモートフォントが含まれていない。
• 永続化されるリーダー状態はオプトイン方式で、名前空間が分離され、サイズが制限され、同一オリジン内に限定され、決定論的な仕様ハッシュの対象外に保たれている。
• 注釈はテキストとしてのみレンダリングされ、実行可能なマークアップを作成できない。
• グローバル再生とローカル再生が1つのステートマシンを共有し、同時に実行されることがない。
• 各トレースのステップで、実際の出辺のパス（またはシンクの入辺のパス）がアクティブになり、ラベルと矢印の状態が一致し、そのステップを裏付ける証拠のみが強調表示される。
• シーンの証拠カードが、検証済み／推定／類推の境界を保ち、リモートプレビューを取得することなく、本文と実用的な参照先を表示する。
• シーンの PNG、PPTX、DOCX パッケージが、想定されるシグネチャと構造を備え、証拠のフッターを含んでいる。Pages のネイティブエクスポートを謳う場合は、Pages で再度開けることも確認済みである。
• モバイルではデスクトップの SVG を縮小せず、積み重ね形式のフローを使用する。
• 最終レポートがユーザーの現在の操作言語に従い、生成した仕様と HTML のパスを明記し、デスクトップ、モバイル、永続化、再生、証拠、エクスポートのブラウザー QA を実施したかどうかを記載している。

証拠が不完全な場合は、証拠マップと注意事項によって不足が明確に伝わる場合に限り、生成してください。それ以外の場合は中止し、不足している証拠を報告してください。