visualize

What this skill does

# Visualize

## Overview

Create source-adjacent HTML visualizations from repository documentation, markdown files, standardized plan folders, and arbitrary user context. This skill is Huashu-derived in workflow discipline, but it is intentionally documentation-focused: it turns real source material into readable maps, timelines, flows, risk blocks, and recommendation diagrams.

## Scope

Use this skill for:

- Documentation and markdown visualization
- Standardized plan folder visualization
- Flow, chart, Mermaid, context map, and recommendation diagram requests
- Source-adjacent HTML summaries that help users inspect structure, risks, decisions, and next steps

Do not use this skill for:

- Brand sites or marketing pages
- Product prototypes or production web apps
- Slide decks, long motion demos, or broad visual design systems

## Output Conventions

- Plan folder: create `visualize.html` and `visualize-assets/` inside the plan folder.
- Brainstorm folder: create `visualize.html` and `visualize-assets/` inside the brainstorm folder.
- Current context tied to an active plan or brainstorm artifact folder: create `visualize.html` and `visualize-assets/` inside that artifact folder.
- Markdown or document file: create `<source-base>.visualize.html` and `<source-base>.visualize-assets/` beside the source file.
- Source-less context with no associated artifact folder: create `docs/.visualizations/<slug>-YYMMDD-HHmm/visualize.html` and `docs/.visualizations/<slug>-YYMMDD-HHmm/visualize-assets/` unless the user specifies a target. Generate the timestamp with `date +%y%m%d-%H%M`.

Always copy `references/templates/visualize-theme.css` into the adjacent assets folder and link the copied local CSS from the generated HTML. Mermaid CDN usage is allowed for diagrams.

## Workflow

1. Load project context when visualizing repository files (if the current session does not already have it).
   - If `docs/SUMMARY.md` exists, read it first.
   - Load only task-relevant detail docs.
   - Prioritize `Code Standard` docs for implementation conventions.
   - If docs conflict with code or user intent, use the available input/question tool before broad changes.
2. Load the source material.
   - For plan folders, read `SUMMARY.md` and relevant `phase-XX-*.md` files.
   - For brainstorm folders, read `SUMMARY.md` and relevant `section-XX-*.md` files.
   - For markdown or document files, read the requested source directly.
   - For current context tied to an active plan or brainstorm artifact folder, use the conversation/request content plus the artifact folder as the output target.
   - For source-less user context with no associated artifact folder, use only the provided conversation/request content.
3. Identify the visualization intent.
   - Determine whether the user needs a plan map, document map, process flow, decision view, recommendation view, or mixed visualization.
   - Ask with the input/question tool only when the source, target, or output ambiguity cannot be resolved safely.
4. Build a compact source inventory before choosing layout.
   - Use `references/workflow.md` and `references/content-patterns.md`.
   - Capture the source hierarchy, entities or files, phases or tasks, dependencies, decisions, risks, blockers, recommendations, verification steps, and missing evidence when present.
   - Treat templates as shells. A block belongs in the output only when it summarizes source-backed content, clarifies a relationship, or exposes a meaningful gap.
5. Choose the template with `references/router.md`.
   - Plan folders use `references/templates/plan.html`.
   - Brainstorm folders use `references/templates/context.html`.
   - Single documents use `references/templates/document.html`.
   - Source-less context uses `references/templates/context.html`.
6. Extract facts and assumptions into the selected block set.
   - Preserve source facts, file paths, statuses, risks, decisions, verification steps, and recommendations.
   - Label assumptions clearly when the source leaves gaps.
7. Compose the HTML.
   - Start from the selected template.
   - Replace `VISUALIZE:` marker regions with source-backed content and remove blocks that do not earn their place.
   - Escape source-derived text before inserting it into HTML unless the text is intentionally authored generated markup.
   - Copy `visualize-theme.css` beside the output before linking it.
8. Add Mermaid diagrams where they clarify structure.
   - Use `references/mermaid-recipes.md`.
   - Prefer several small diagrams over one dense diagram.
   - Skip Mermaid when a diagram would only restate headings or duplicate nearby prose.
   - Use readable HTML/CSS fallback blocks when Mermaid syntax is uncertain.
9. Verify the output with `references/verification.md`.

## Rules

- Do not invent facts, fake metrics, fake decisions, fake users, fake constraints, or unsupported recommendations.
- Do not hide missing source content. Add an assumption or warning block instead.
- Keep visualizations factual, source-adjacent, and easy to inspect.
- Keep templates and generated HTML focused on documentation visualization, not broad design/prototype work.
- Avoid large inline style blocks; use the copied fixed theme CSS.
- Escape source-derived text before writing it into HTML unless it is intentional generated markup authored by the agent.
- Preserve source links and paths when they help the user trace content back to origin.