deep-research-visualize

/deep-research-visualize — Rich HTML Report Generation

Trigger

Invoked with /deep-research-visualize followed by a report directory path and optional theme.

/deep-research-visualize [report-directory] [--theme editorial|blueprint|paper|midnight]

• [report-directory] -- Path to a research output directory containing a /deep-research report. Defaults to the most recent directory under ${CLAUDE_PLUGIN_DATA}/research/ if omitted.
• --theme -- Visual theme. Default: editorial. Themes are defined in ${CLAUDE_PLUGIN_ROOT}/skills/deep-research-visualize/themes/manifest.json.
  • editorial -- business/strategy (warm white + charcoal + serif)
  • blueprint -- technical/engineering (steel blue + sans-serif)
  • paper -- academic/formal (black + white + crimson)
  • midnight -- dark mode (slate + teal)

Purpose

Transform a Markdown research report into a boardroom-ready HTML file. The default output uses CDN links for fast loading and small file size (~70 KB). An optional offline version can be generated that is fully self-contained with zero external dependencies (~3.5 MB).

This is a post-processing skill -- it does not perform research. It takes the output of /deep-research and produces a visual artifact.

Workflow

Subagent output protocol: every subagent spawn in this skill follows the output protocol defined in the research skill. The orchestrator prepends the Spawn Preamble to each spawn prompt with:

• <WRITE-PATH> = ${CLAUDE_PLUGIN_DATA}/scratch/deep-researcher-<ISO-timestamp>-<random-12>.md
• Agent type: deep-researcher:deep-researcher with appropriate role

1. Resolve Input

Determine the source report directory:

• If report-directory is provided, validate it exists.
• If omitted, find the most recent directory under ${CLAUDE_PLUGIN_DATA}/research/.

Determine the topic slug from the report directory name.

Three-way pipeline detection -- after resolving the topic directory, inspect its contents:

1. Emitter path -- groupings.json exists in the topic directory -> proceed directly to Step 3 (read groupings.json) and Step 4 (emitter invocation).
2. Pre-emitter path -- dimension directories exist (subdirectories under the topic directory) but no groupings.json -> first run the report pipeline steps to produce groupings.json and page-N.md files, then proceed to Step 3 and Step 4.
3. Legacy path -- neither dimension directories nor groupings.json exist, but report.md exists -> skip to the legacy Coder subagent (Step 4 legacy branch) and apply make-offline.ts (Step 5).

2. Determine Theme

1. Read ${CLAUDE_PLUGIN_ROOT}/skills/deep-research-visualize/themes/manifest.json to discover available themes.
2. Validate the requested theme ID exists in the manifest. If not found, fall back to editorial (the default).
3. Note the theme's css file path and fonts.googleFontsUrl.

Theme	Use Case	Palette
editorial	Business/strategy (default)	Charcoal on warm white, serif
blueprint	Technical/engineering	Steel blue on light gray, sans-serif
paper	Academic/formal	Black on white with crimson accent
midnight	Dark mode / low-light	Slate with teal accents

3. Read Report Structure

Emitter path (groupings.json present): The orchestrator reads the groupings.json directly -- it is small JSON and no subagent is needed. Extract from it:

• Total page count (number of entries in the groupings array)
• Page titles and theme_hint values

This is the complete input brief for the emitter in Step 4.

Legacy path (report.md only): The orchestrator reads the report's structure (headings, tables, Mermaid blocks) to build a brief for the Coder subagent. Do not read the full body -- pass the path to the Coder and let it read.

4. Generate HTML

4a. Emitter path (groupings.json present)

Invoke the report pipeline emitter:

npx tsx ${CLAUDE_PLUGIN_ROOT}/skills/deep-research-visualize/scripts/reportPipelineEmitter.ts \
  --groupings <RESOLVED_TOPIC_DIR>/groupings.json \
  --theme editorial \
  --plugin-dir ${CLAUDE_PLUGIN_ROOT}/skills/deep-research-visualize/

Replace <RESOLVED_TOPIC_DIR> with the resolved topic directory path and editorial with the requested theme ID.

The emitter writes both report.html and report-offline.html atomically to the topic directory. No separate offline step is needed -- proceed directly to Step 6 (Visual Verification).

4b. Legacy path (report.md only, no groupings.json)

Spawn coder subagent (agent: deep-researcher:deep-researcher, role: coder) with:

• Report file path
• Output path: <RESOLVED_TOPIC_DIR>/report.html
• Theme ID (e.g., editorial)
• Paths to theme files:
  • ${CLAUDE_PLUGIN_ROOT}/skills/deep-research-visualize/themes/manifest.json
  • ${CLAUDE_PLUGIN_ROOT}/skills/deep-research-visualize/themes/_base.css
  • ${CLAUDE_PLUGIN_ROOT}/skills/deep-research-visualize/themes/<theme>.css
• Reference docs path: ${CLAUDE_PLUGIN_ROOT}/skills/deep-research-visualize/references/html-template.md

Coder instructions:

1. Read manifest.json to find the selected theme's metadata, font URL, Mermaid themeVariables, and Chart.js chartColors.
2. Read _base.css and <theme>.css. Concatenate them into a single <style> block in the HTML <head>.
3. Read the reference docs (html-template.md) for transformation rules and the "Known Pitfalls" section.
4. Read the source report.md.
5. Sanitize Mermaid blocks BEFORE converting to HTML:
   • Scan all ```mermaid code blocks for HTML tags (<br>, <video>, <b>, etc.) and special characters (&, <, >) inside node labels
   • Replace HTML tags with plain text or spaces
   • Wrap ALL node labels in double quotes: A["Label"] not A[Label]
   • Escape & as & inside Mermaid content
6. Escape HTML in code blocks: Before converting inline code or fenced code blocks to <code> / <pre><code>, escape bare < as < and > as > inside the code content. Do NOT double-escape -- if the source already contains < or > (HTML entities), leave them as-is.
7. Generate a single self-contained HTML file per the template in the reference docs.
8. Initialize Mermaid in a <script> block at the bottom:

   mermaid.initialize({
     theme: 'base',
     themeVariables: { /* copy from manifest.json theme.mermaid.themeVariables */ }
   });
   

9. Map Markdown elements per the transformation rules.
   • Tables: ALWAYS wrap <table> in <div class="table-wrap">...</div>
   • Use <span class="badge badge-high|medium|low"> for confidence labels
10. Write the HTML file to the output path.

5. Generate Offline Copy (Legacy Path Only)

This step applies only when Step 4b (legacy Coder subagent) was used. On the emitter path (Step 4a), both report.html and report-offline.html are already written atomically by the emitter -- skip this step entirely.

npx tsx ${CLAUDE_PLUGIN_ROOT}/skills/deep-research-visualize/scripts/make-offline.ts \
  <RESOLVED_TOPIC_DIR>/report.html \
  --theme <theme-id> \
  --vendor-dir ${CLAUDE_PLUGIN_ROOT}/skills/deep-research-visualize/vendor/

This creates report-offline.html in the same directory by inlining:

• Mermaid.js from vendor/[email protected]
• Chart.js from vendor/[email protected]
• Google Fonts from vendor/fonts/<theme>-inline.css

The offline file is fully self-contained (zero network requests) but large (~3.5 MB).

6. Visual Verification (Mandatory)

Before presenting to the user, the orchestrator MUST verify the HTML renders correctly. Do not skip this step -- Mermaid syntax errors, table truncation, and CSS issues are easy to introduce and hard to spot from source alone.

If Playwright MCP is available:

1. Serve the HTML via a local HTTP server (python3 -m http.server <port> in the report directory).
2. Navigate to http://localhost:<port>/report.html in a headless browser.
3. Check the browser console for errors (especially Mermaid syntax errors).
4. Scroll through key sections and take screenshots.
5. Fix any issues found before presenting.
6. Stop the HTTP server when done.

Orchestrator pre-validation (do before spawning Coder on legacy path): The orchestrator should scan the source for all Mermaid blocks and do a quick syntax sanity check. If any of these patterns are found, fix them:

• HTML tags inside node text: <br>, <video>, <b>, etc. -> replace with plain text
• Unquoted colons in diamond nodes: {text: with colon} -> {"text with colon"}
• Bare & characters -> &
• Unquoted node labels with spaces: A[Label with spaces] -> A["Label with spaces"]

7. Open in Browser and Report Paths

After verification passes, print the full absolute paths:

Report ready:

  report.html (local server):
  file://<ABSOLUTE_OUTPUT_DIR>/report.html

  report-offline.html (self-contained, open directly):
  file://<ABSOLUTE_OUTPUT_DIR>/report-offline.html

Then open the offline file in the system browser:

• macOS: open <ABSOLUTE_OUTPUT_DIR>/report-offline.html
• Linux: xdg-open <ABSOLUTE_OUTPUT_DIR>/report-offline.html

Transformation Rules

Structure Mapping

Markdown Element	HTML Output
# Title	<h1> with page header styling and bottom border
## Section	<h2> with section divider border
### Subsection	<h3> in theme primary color
#### Point	<h4>
[^N^] citations	<span class="citation"> superscript
Tables	<table> with styled headers, hover rows, responsive scroll
Mermaid code blocks	<div class="mermaid"> (rendered by Mermaid.js)
Bullet lists	<ul> with styled bullets
Numbered lists	<ol>
Callout blocks (> **Note**)	<div class="callout">
Conflict zone sections	<div class="conflict-zone"> with warning label
Source lists	<details> collapsible sections

Chart.js Data Visualization

When the report contains tables with >=3 rows of numeric data:

• Extract data into a Chart.js <canvas> element
• Use bar chart for comparisons, line for trends, pie for share
• Place chart directly below the source table
• Add .chart-source attribution line
• Use responsive sizing: maintainAspectRatio: true

Output Files

The emitter (Step 4a) always writes two files:

• report.html -- development/server artifact. CSS and vendor JS are copied as co-located files and referenced via relative <link> / <script> tags. Requires an HTTP server from the output directory.
• report-offline.html -- fully self-contained single file. All CSS (base + theme + embedded font-faces) and Mermaid JS are inlined. Opens directly from file:// with no network or server required.

Both files must include <meta charset="UTF-8"> and <meta name="viewport">.

Constraints

• No research. This skill only converts existing Markdown. If the user wants new research, route to /deep-research.
• Two-file output. The emitter always writes both report.html (requires co-located assets + HTTP server) and report-offline.html (fully self-contained, opens from file://).
• report-offline.html is the shareable artifact.
• Emitter path is authoritative. When groupings.json is present, always use the emitter (Step 4a). Do not fall back to the Coder subagent (Step 4b) when the emitter path is available.
• Coder does generation on the legacy path. When falling back to the legacy path (report.md only), the orchestrator does not generate HTML inline; it delegates to a Coder subagent to keep context clean.
• make-offline.ts is legacy-only. Do not invoke make-offline.ts on the emitter path -- the emitter already writes both report.html and report-offline.html.