publish-html-report

HTML レポートの公開

これは参考パターンです。 このアプローチから学び、状況に合わせて調整してください。そのままコピーしないでください。

問題：Markdown ではリッチなビジュアライゼーションに限界があります。依存関係グラフ、変更前後のアーキテクチャ図、レイヤー化された断面図、インタラクティブな Mermaid チャートは、GitHub の Markdown ではうまく（あるいはまったく）表示されません。

解決策：Tailwind と Mermaid の CDN を使って自己完結型の HTML ファイルを生成し、非公開の GitHub gist として公開してから、htmlpreview.github.io を使って閲覧可能な URL を作成します。

---

パターン

ワークフロー：

Generate HTML → Write to docs/  → Push to branch
                                → Create secret gist
                                → Construct preview URL (htmlpreview.github.io)
                                → Link in PR description

この方法が有効な理由：

• 非公開 gist は一覧には表示されませんが、raw URL からは誰でもアクセスできます
• htmlpreview.github.io は GitHub の raw HTML を取得してレンダリングします
• GitHub Pages、有料プラン、ホスティング基盤は不要です

---

HTML のひな型

各レポートは、CDN 以外の外部アセットを必要としない、自己完結型の単一ファイルです。

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>{{Report Title}}</title>
    <script src="https://cdn.tailwindcss.com"></script>
    <script type="module">
      import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";
      mermaid.initialize({ startOnLoad: true, theme: "neutral", securityLevel: "loose" });
    </script>
  </head>
  <body class="bg-stone-50 text-slate-900 font-sans">
    <main class="max-w-5xl mx-auto px-6 py-12 space-y-12">
      <header>
        <h1 class="text-3xl font-bold">{{Title}}</h1>
        <p class="text-sm text-slate-500">{{date}} · {{repo-name}}</p>
      </header>
      
    </main>
  </body>
</html>

ルール：

• 使用できる CDN スクリプトは Tailwind と Mermaid のみです
• アプリのコードは禁止です。Mermaid のレンダリング以外のインタラクティブ機能も使用できません
• ローカルで開いたときに、ファイルが正しくレンダリングされる必要があります（open file.html）

---

図のテクニック

これらを組み合わせ、すべての図が同じ見た目にならないようにしてください。

Mermaid — 呼び出しフロー、依存関係、シーケンスなど、グラフ形式の関係に使用します。

<div class="rounded-lg border border-slate-200 bg-white p-4">
  <pre class="mermaid">
    flowchart LR
      A[Module] --> B[Dependency]
      B -.-> C[Leaking concern]
  </pre>
</div>

手作りの div — Mermaid のレイアウトが合わない場合に使用します（大規模な図、レイヤー化された断面図、モジュールの深さの比較など）。

<div class="relative border rounded p-4">
  <div class="h-8 border-l-4 border-indigo-500 pl-3 flex items-center text-xs">Interface</div>
  <div class="h-32 border-l-4 border-slate-300 pl-3 flex items-center text-xs">Implementation</div>
</div>

インライン SVG — 配置した要素間の矢印や接続線に使用します。

---

公開ワークフロー

1. レポートを書く

docs/reports/<date>-<slug>.html に配置します。同じパスに拡張子を .md にした Markdown の代替版も作成します。

2. 非公開 gist を作成する

gh gist create docs/reports/<date>-<slug>.html \
  --desc "<Report Title> — <repo-name> (<date>)"

3. プレビュー URL を作成する

GIST_ID=$(gh gist list --limit 1 | head -1 | awk '{print $1}')
RAW_URL=$(gh api gists/$GIST_ID --jq '.files | to_entries[0].value.raw_url')
echo "https://htmlpreview.github.io/?$RAW_URL"

4. PR の説明にリンクを記載する

📄 **[Report Title — Visual](<HTMLPREVIEW_URL>)** — opens in browser
📄 **[Markdown fallback](docs/reports/<date>-<slug>.md)** — renders on GitHub

5. クリーンアップの規約

マージ前に docs/reports/ を削除対象として指定します。

> ⚠️ **CLEANUP**: Delete `docs/reports/` directory before merging.

レポートはレビュー用の一時的な成果物であり、恒久的なドキュメントではありません。

---

統合：アーキテクチャレビュー（mattpocock/skills）

improve-codebase-architecture スキルと併用する場合：

1. アーキテクチャ分析を実行します（調査、候補の特定）
2. そのスキルの HTML-REPORT 形式（候補カード、変更前後の図、推奨バッジ）に従って HTML レポートを生成します
3. このスキルの gist ワークフローを使って公開します
4. 候補一覧表とプレビューリンクを含む PR を作成します
5. フォローアップ用のマルチエージェントワークフローの手順を記載します。

### How to Work on This

1. `/to-prd` — generate PRD from candidates
2. `/to-issues` — one issue per candidate
3. Execute each issue in a separate session
4. `/grill-me` for deeper design decisions

---

アーキテクチャ以外のユースケース

このパターンは、Markdown より HTML が適したあらゆるビジュアライゼーションで有効です。

• 依存関係グラフ — 色分けした健全性指標付きのモジュール間の関係
• テストカバレッジマップ — カバレッジの不足箇所を示す視覚的なヒートマップ
• パフォーマンスレポート — グラフを使った変更前後の所要時間の比較
• 移行の進捗状況 — 複数ステップの移行状況の可視化
• データフロー図 — 分岐ロジックを含む複雑なパイプライン
• API の表面積 — インターフェースの広がりを示すビジュアライゼーション

内容に合わせて、ひな型と図のテクニックを調整してください。公開ワークフローは変わりません。

---

スタイルの指針

• 企業向けダッシュボードではなく、編集記事のようなスタイルにします。余白を十分に取ります。
• 色は控えめに使います。アクセントカラーを1色（エメラルド／インディゴ）にし、問題には赤、警告にはアンバーを使います。
• 図の高さは約320pxにし、変更前後を横並びで表示できるようにします。
• 図のラベルには text-xs uppercase tracking-wider を使用します。
• 見出しにセリフ体（font-serif）を使うのは任意です。ストーン／スレートのカラーパレットと組み合わせます。

---

代替手段

gh gist create が失敗した場合（認証の問題、レート制限など）：

1. Markdown のみのバージョンに切り替えます
2. HTML をローカルで開く方法を記載します：open docs/reports/<file>.html

---

段階的な改善

開発者から、このスキルで防げるはずだった動作について修正を受けた場合は、同じ指摘を今後防ぐために、このスキルへ追加する具体的な修正を提案してください。