spec-to-readable-html

name	spec-to-readable-html
description	Markdown やテキスト仕様書を、要約・構造再編・図表・チャート・ソーストレーサビリティ付きの読みやすい HTML ドキュメントに変換します。仕様書、要件定義、API 仕様、プロダクト仕様、設計ドキュメント、技術文書を可読性の高い HTML に変換したい場合や、要約・再構成・ダイアグラム・グラフ・画像・ビジュアル補助が必要な場合に使用してください。
argument-hint	[lang]
arguments	lang
metadata	{"version":"1.0.0","tier":"stable","category":"document","tags":["html","spec","markdown","documentation","diagram"]}

spec-to-readable-html

仕様書を洗練されたHTMLレポートに変換するスキル。単純なMarkdown→HTMLへの変換ではなく、ソースを分析・要約・再構成し、視覚補助を追加して理解しやすいドキュメントを生成する。

$lang で出力言語を指定する（デフォルト: ja）。省略した場合は日本語で出力する。

動作環境

このスキルは Windows / macOS / Linux のいずれでも動作する。 出力する HTML は完全にスタンドアロン（CDN 依存なしオプションあり）のため、オフライン環境でも閲覧可能。

使用するタイミング

以下のような依頼でこのスキルを使用する:

• 仕様書・要件定義・設計ドキュメント・API 仕様・PRD・RFC・技術文書を HTML に変換する
• Markdown の仕様書を人間が読みやすい形式にする
• 要約・図表・チャート・スクリーンショット・アイコン・視覚補助を追加する
• 密度の高い要件を読みやすいウェブページやレポートにする
• エグゼクティブサマリー・実装概要・APIマップ・ワークフロー・アーキテクチャ図・意思決定サマリーを生成する

注意: ユーザーが明示的に「忠実な変換」を求めた場合のみ、単純なMarkdown→HTML変換として扱う。

コア原則

1. 理解しやすさを優先する（書式だけでなく）

   • 長いセクションを要約する
   • 関連情報をグループ化する
   • 重要な意思決定・リスク・依存関係・未解決事項を表面化する

2. トレーサビリティを保持する

   • 意味をサイレントに変更しない
   • 推論したコンテンツは Inferred（推論）または Assumption（前提）とマークする
   • 可能な限り元のセクション名へのリンクや参照を残す

3. 視覚補助は必要な場合のみ使用する

   • フロー・関係性・アーキテクチャ・状態遷移・タイムライン・データモデルに図を追加する
   • ソースに比較可能な数量・優先度・タイムライン・ステータス・カテゴリが含まれる場合のみチャートを追加する
   • 定量的なデータを作り上げない

4. 出力をポータブルにする

   • 埋め込み CSS を持つスタンドアロン HTML ファイルを優先する
   • ユーザーが明示的に許可しない限り外部依存を避ける
   • Mermaid や外部チャートライブラリを使用する場合はその依存を説明する
   • 完全スタンドアロン版: CDN が使えない環境では、Mermaid ブロックをインライン SVG に置き換えて完全に自己完結したファイルを生成する

入力の処理

以下のいずれの入力も受け付ける:

• Markdown ファイル
• プレーンテキストの仕様書
• 複数の関連仕様ファイル
• API スキーマ / OpenAPI フラグメント
• README スタイルのプロダクト・技術ノート
• 改善が必要な既存 HTML

HTML を生成する前に以下を特定する:

• ドキュメントタイプ: PRD / API仕様 / 技術仕様 / 設計ドキュメント / 運用手順書など
• 対象読者: ビジネス / エンジニアリング / QA / 運用 / 混在
• 主要エンティティ: ユーザー・システム・API・画面・ジョブ・データモデル
• 主要プロセス: ワークフロー・シーケンス・状態遷移
• 曖昧な点・未決定事項・リスク

対象読者や求める詳細レベルが不明な場合は以下をデフォルトとする:

• 対象: プロダクト + エンジニアリング混在
• 詳細度: 読みやすいが実装を意識したレベル
• 出力: 単一のスタンドアロン HTML ドキュメント

推奨ワークフロー

1. ソースを読み込みマッピングする

   • タイトル・目的・スコープ・背景・要件・フロー・API・データ・制約・リスク・未解決事項を抽出する

2. 読者に優しい構造を作る

   • エグゼクティブサマリー
   • このドキュメントのカバー範囲
   • 主要概念 / 用語集
   • 主要ワークフローまたはユーザージャーニー
   • 機能要件
   • 非機能要件
   • システム / API / データ概要
   • 視覚的な図表
   • リスク・前提・未解決事項
   • 付録: ソース対応の詳細

3. 選択的に要約する

   • 要件・APIコントラクト・制約・受け入れ基準の詳細は正確に保持する
   • 背景・動機・繰り返しの説明・長い文章は要約する
   • 重要なノートには callout を使用する

4. 視覚補助を選択する

   • 下記の視覚決定ガイドを使用する
   • 環境とユーザーの好みに応じて、インライン SVG・Mermaid ソース・画像ファイルとして図を作成する
   • 必ずキャプションと alt テキストを追加する

5. 洗練された HTML を生成する

   • セマンティック HTML を使用: section・article・nav・table・figure・figcaption
   • 長いドキュメントにはスティッキーまたはトップの目次を含める
   • 読みやすいタイポグラフィ・スペーシング・コントラストを使用する
   • 必要に応じて印刷フレンドリーな CSS を含める

6. 出力を検証する

   • ソースの意味が保持されているか確認する
   • 前提が適切にラベル付けされているか確認する
   • 視覚補助がソースと一致しているか確認する
   • 依存関係が明示されているか、または HTML が単独で開けるか確認する

視覚決定ガイド

コンテンツに基づいて視覚補助を選択する:

ソースコンテンツ	最適な視覚補助
ステップバイステップのビジネス・ユーザープロセス	フローチャート
システム間の API コール	シーケンス図
システムコンポーネントと依存関係	アーキテクチャ図
ステータスのライフサイクル	状態図
エンティティと関係のテーブル	ER図 / 関係マップ
マイルストーンやフェーズドロールアウト	タイムライン
優先度・ステータス・カテゴリのカウント	棒グラフ / スタックグラフ
決定の代替案	比較マトリクス
画面遷移	ユーザージャーニー / サイトマップ
長いセクション構造	サマリーカード

優先フォーマット:

1. インライン SVG — スタンドアロンの視覚的な図やチャートに使用
2. Mermaid — ソースの可読性が重要なアーキテクチャ・フローチャート・シーケンス・状態・ER図
3. HTML/CSS カードとテーブル — サマリーと比較
4. ラスタ画像 — 画像生成やスクリーンショットが明示的に要求された場合のみ

Mermaid を使用する場合は、後で編集できるように Mermaid ソースを HTML または付録に含める。

HTML 出力要件

完全な HTML ファイルを生成する際は references/template.html をベース HTML テンプレートとして、references/html-output-template.md をコンポーネントガイドとして使用する。テンプレートから完全な <style> ブロックとセクション構造をコピーし、{{PLACEHOLDER}} トークンをソースから導出したコンテンツに置き換える。

HTML には通常以下を含める:

• ドキュメントタイトルと短いサブタイトル
• 生成日またはソースバージョン（分かる場合）
• エグゼクティブサマリー
• 目次
• 重要ポイントのサマリーカード
• 簡潔な見出しのあるメインセクション
• 要件・API・データフィールド・決定・リスク・未解決事項のテーブル
• キャプション付きの視覚的な図
• ソーストレーサビリティノート
• 印刷フレンドリーなスタイリング

密度の高い技術仕様には以下のバッジを含める:

• Must・Should・Could
• Confirmed・Inferred・Assumption・Open Question
• High Risk・Medium Risk・Low Risk

出力ファイルの保存

生成した HTML ファイルの保存先:

• デフォルト: 入力ファイルと同じディレクトリ、またはカレントディレクトリ
• ファイル名: [元のファイル名]-readable.html（例: spec.md → spec-readable.html）
• Windows でも macOS / Linux でも、パス区切り文字は自動的に解決される

要約と推論のルール

• 要約したことを示さずに契約的・規範的な要件を削除しない
• MUST・SHOULD・SHALL・required・optional・deprecated などのキーワードを保持する
• ID・エンドポイントパス・フィールド名・ステータス名・列挙値・エラーコード・制限を正確に保持する
• 図が解釈を必要とする場合は「推論ビュー」としてラベル付けする
• ソースが曖昧な場合は推測する代わりに Open Questions セクションを作成する

言語

デフォルトの出力言語は日本語（<html lang="ja">）。ユーザーが別の言語を要求した場合はすべての見出し・バッジ・ラベル・本文テキストにその言語を使用する。技術用語（API名・フィールド名・パス・コード識別子）は言語に関わらず元の言語で保持する。

品質チェックリスト

最終化する前に確認する:

• 出力がソースより読みやすく、単なる変換以上のものになっている
• 重要な要件と制約が保持されている
• 要約が意味を変えていない
• 視覚補助が正確で有用である
• 推論コンテンツと前提がラベル付けされている
• 構造化された詳細にテーブルが使用されている
• HTML に目次がある
• ファイルがスタンドアロンであるか、依存関係が文書化されている
• アクセシビリティの基本が対応されている: 見出し・コントラスト・alt テキスト / キャプション