visualize

可視化

概要

リポジトリのドキュメント、Markdown ファイル、標準化された計画フォルダー、任意のユーザーコンテキストから、ソースに隣接する HTML の可視化を作成します。このスキルはワークフローの規律において Huashu に由来しますが、意図的にドキュメントに特化しています。実際のソース資料を、読みやすいマップ、タイムライン、フロー、リスクブロック、推奨図に変換します。

範囲

このスキルは、次の用途に使用します。

• ドキュメントと Markdown の可視化
• 標準化された計画フォルダーの可視化
• フロー、チャート、Mermaid、コンテキストマップ、推奨図のリクエスト
• 構造、リスク、判断、次のステップを確認するのに役立つ、ソースに隣接した HTML の要約

このスキルは、次の用途には使用しないでください。

• ブランドサイトやマーケティングページ
• 製品プロトタイプや本番用 Web アプリ
• スライドデッキ、長尺のモーションデモ、幅広いビジュアルデザインシステム

出力規約

• 計画フォルダー：計画フォルダー内に visualize.html と visualize-assets/ を作成します。
• ブレインストーミングフォルダー：ブレインストーミングフォルダー内に visualize.html と visualize-assets/ を作成します。
• 進行中の計画またはブレインストーミング成果物フォルダーに関連する現在のコンテキスト：その成果物フォルダー内に visualize.html と visualize-assets/ を作成します。
• Markdown またはドキュメントファイル：ソースファイルと同じ場所に <source-base>.visualize.html と <source-base>.visualize-assets/ を作成します。
• 関連する成果物フォルダーのない、ソースを伴わないコンテキスト：ユーザーが保存先を指定しない限り、docs/.visualizations/<slug>-YYMMDD-HHmm/visualize.html と docs/.visualizations/<slug>-YYMMDD-HHmm/visualize-assets/ を作成します。date +%y%m%d-%H%M でタイムスタンプを生成します。

必ず references/templates/visualize-theme.css を隣接するアセットフォルダーにコピーし、生成した HTML からコピー先のローカル CSS を参照してください。図には Mermaid CDN を使用できます。

ワークフロー

1. リポジトリのファイルを可視化する際は、プロジェクトのコンテキストを読み込みます（現在のセッションですでに読み込まれている場合を除きます）。
   • docs/SUMMARY.md が存在する場合は、まず読みます。
   • タスクに関連する詳細ドキュメントのみを読み込みます。
   • 実装規約については、Code Standard ドキュメントを優先します。
   • ドキュメントの内容がコードやユーザーの意図と矛盾する場合は、大規模な変更を行う前に、利用可能な入力／質問ツールを使用します。
2. ソース資料を読み込みます。
   • 計画フォルダーの場合は、SUMMARY.md と関連する phase-XX-*.md ファイルを読みます。
   • ブレインストーミングフォルダーの場合は、SUMMARY.md と関連する section-XX-*.md ファイルを読みます。
   • Markdown ファイルやドキュメントファイルの場合は、指定されたソースを直接読みます。
   • アクティブな計画またはブレインストーミングの成果物フォルダーに関連する現在のコンテキストの場合は、会話／リクエストの内容と成果物フォルダーを出力先として使用します。
   • 関連する成果物フォルダーのない、ソース資料を伴わないユーザーのコンテキストの場合は、提供された会話／リクエストの内容のみを使用します。
3. 可視化の意図を特定します。
   • ユーザーが必要としているものが、計画マップ、ドキュメントマップ、プロセスフロー、意思決定ビュー、推奨事項ビュー、または複合的な可視化のいずれかを判断します。
   • ソース、対象、または出力の曖昧さを安全に解決できない場合に限り、入力／質問ツールを使用します。
4. レイアウトを選ぶ前に、簡潔なソースの一覧を作成します。
   • references/workflow.md と references/content-patterns.md を使用します。
   • ソースにある場合は、階層、エンティティまたはファイル、フェーズまたはタスク、依存関係、意思決定、リスク、ブロッカー、推奨事項、検証手順、不足している根拠を記録します。
   • テンプレートはひな型として扱います。ソースに基づく内容を要約する、関係を明確にする、または重要な不足を明らかにする場合にのみ、そのブロックを出力に含めます。
5. references/router.md を使ってテンプレートを選びます。
   • 計画フォルダーには references/templates/plan.html を使用します。
   • ブレインストーミングフォルダーには references/templates/context.html を使用します。
   • 単一ドキュメントには references/templates/document.html を使用します。
   • ソース資料を伴わないコンテキストには references/templates/context.html を使用します。
6. 事実と前提を抽出し、選択したブロックに整理します。
   • ソースに記載された事実、ファイルパス、ステータス、リスク、意思決定、検証手順、推奨事項を保持します。
   • ソースに不足がある場合は、前提であることを明確に示します。
7. HTML を作成します。
   • 選択したテンプレートから始めます。
   • VISUALIZE: マーカーの領域をソースに基づく内容で置き換え、不要なブロックは削除します。
   • 意図的に作成したマークアップではない限り、HTML に挿入する前に、ソース由来のテキストをエスケープします。
   • リンクを設定する前に、visualize-theme.css を出力先の隣にコピーします。
8. 構造を明確にできる場合は、Mermaid 図を追加します。
   • references/mermaid-recipes.md を使用します。
   • 1 つの密な図より、複数の小さな図を優先します。
   • 図が見出しの言い換えや近くにある文章の重複にしかならない場合は、Mermaid を使いません。
   • Mermaid の構文に確信が持てない場合は、読みやすい HTML／CSS の代替ブロックを使用します。
9. references/verification.md を使って出力を検証します。

ルール

• 事実、架空の指標、架空の意思決定、架空のユーザー、裏付けのない制約、根拠のない推奨事項を作り出さないでください。
• ソース内容の不足を隠さないでください。代わりに、前提または警告のブロックを追加します。
• 可視化は事実に基づき、ソースに即した、確認しやすいものにします。
• テンプレートと生成する HTML は、幅広いデザイン／プロトタイプ作業ではなく、ドキュメントの可視化に焦点を絞ります。
• 大きなインラインスタイルブロックは避け、コピーした固定のテーマ CSS を使用します。
• エージェントが意図的に生成したマークアップでない限り、HTML に書き込む前に、ソース由来のテキストをエスケープします。
• ユーザーが内容の出所をたどるのに役立つ場合は、ソースへのリンクとパスを保持します。