Visualize

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.
• Markdown or document file: create <source-base>.visualize.html and <source-base>.visualize-assets/ beside the source file.
• Source-less context: create visualize-YYMMDD-HHmm-<slug>.html and a matching assets folder in the current working directory 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).

• Follow the shared Context Loading Protocol: read docs/SUMMARY.md first, then load only directly relevant detail files.

2. Load the source material.

• For plan folders, read SUMMARY.md and relevant phase-XX-*.md files.
• For markdown or document files, read the requested source directly.
• For source-less user context, 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 question tool only when the source, target, or output ambiguity cannot be resolved safely.

4. Choose the template with references/router.md.

• Plan folders use references/templates/plan.html.
• Single documents use references/templates/document.html.
• Source-less context uses references/templates/context.html.

5. Extract facts and assumptions.

• Use references/workflow.md and references/content-patterns.md.
• Preserve source facts, file paths, statuses, risks, decisions, verification steps, and recommendations.
• Label assumptions clearly when the source leaves gaps.

6. Compose the HTML.

• Start from the selected template.
• Replace VISUALIZE: marker regions with source-backed content.
• Copy visualize-theme.css beside the output before linking it.

7. Add Mermaid diagrams where they clarify structure.

• Use references/mermaid-recipes.md.
• Prefer several small diagrams over one dense diagram.
• Use readable HTML/CSS fallback blocks when Mermaid syntax is uncertain.

8. 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.
• Preserve source links and paths when they help the user trace content back to origin.

Content Patterns

Use these blocks as needed. Keep labels factual and compact.

Source Header

Show title, source path, source type, generated timestamp, and any source metadata present in the file.

Section Map

Turn top-level headings into a navigable list. Add one factual sentence per section when the source provides enough detail.

Key Takeaways

Use three to six bullets that summarize source-backed facts. Do not invent impact or priority.

Phase Timeline

For plans, show phase name, status, objective, touched files, and verification command. Preserve [ ], [-], and [x] states.

Task Checklist

Use source task wording where practical. Group by phase or section.

Risk Matrix

List risk, trigger, impact, and mitigation. If impact or mitigation is not present, mark it as missing instead of guessing.

Decision Or Recommendation Block

Separate source decisions from recommendations. A recommendation must cite the source fact or gap that supports it.

Assumption Block

Use when output location, title, ordering, or grouping is inferred. Keep assumptions visibly labeled.

Warning Block

Use for missing files, ambiguous source content, unsupported diagrams, or verification limitations.

Mermaid Recipes

Prefer several small diagrams over one dense diagram. Keep labels factual and short. If Mermaid syntax is uncertain, use a readable HTML/CSS block instead.

Process Flow

flowchart TD
  A[Load source] --> B[Extract facts]
  B --> C[Choose template]
  C --> D[Verify output]

Timeline

timeline
  title Plan Phases
  Phase 1 : Add shell
  Phase 2 : Add references
  Phase 3 : Align docs

Journey

journey
  title User Review Journey
  section Inspect
    Open visualization: 4: User
    Trace source links: 5: User

Status Transitions

stateDiagram-v2
  [*] --> Pending
  Pending --> InProgress
  InProgress --> Complete
  InProgress --> Blocked

Actor Or System Interaction

sequenceDiagram
  participant User
  participant Agent
  participant Source
  User->>Agent: Request visualization
  Agent->>Source: Read source files
  Agent-->>User: HTML output

Priority Or Risk Map

quadrantChart
  title Risk Priority
  x-axis Low likelihood --> High likelihood
  y-axis Low impact --> High impact
  Missing source detail: [0.6, 0.5]

Use a table fallback for risk maps when labels are long or quadrant placement is not source-backed.

Template Router

Choose the smallest template that fits the requested source.

Routes

Fallbacks

• Mixed inputs: use the dominant source type and add a source list block.
• Directory without plan files: treat as mixed context only if the user supplied enough content; otherwise ask.
• Missing requested file: stop and report the missing path.
• Multiple possible output locations: prefer source-adjacent output when a source path exists.
• Existing output file: overwrite only when that is the obvious user request or the file was generated in the current task; otherwise ask.

Asset Paths

Plan templates link ./visualize-assets/visualize-theme.css. Document and context outputs may need the asset folder name adjusted to <source-base>.visualize-assets/ or visualize-YYMMDD-HHmm-<slug>.visualize-assets/.

Verification

Run these checks before delivering a visualization.

Required Checks

• HTML file exists and opens as text without malformed template markers.
• CSS link resolves to a copied local visualize-theme.css.
• Mermaid CDN script is present when Mermaid blocks are used.
• mermaid.initialize({ startOnLoad: true }) is present.
• Diagram containers are not empty and Mermaid source remains readable before render.
• Source metadata is visible.
• Text does not overlap at desktop width.
• Missing source content is shown as an assumption or warning, not silently filled in.

Optional Browser Check

When browser or Playwright tooling is available:

1. Open the generated HTML. 2. Capture a screenshot at desktop width. 3. Confirm the page is not blank. 4. Confirm the primary layout, Mermaid blocks, and warning/assumption blocks render without overlap.

Visualization Workflow

Use an HTML-first workflow for documentation visualization. The output should make source structure easier to inspect without changing the source material.

Checkpoints

• Small docs and standard plan folders: proceed in one pass, then verify.
• Ambiguous, mixed, or high-volume sources: ask once with the question tool before generating output.
• Missing source files: stop unless a safe fallback source was explicitly provided.

Source Extraction Checklist

Capture only source-backed content:

• Title or inferred title
• Source path
• Created or updated metadata when present
• Section map
• Tasks, statuses, owners, and dependencies when present
• Risks, mitigations, blockers, and open questions
• Decisions and recommendations
• Verification steps and expected results
• Explicit assumptions when the source leaves gaps

Composition Steps

1. Choose the route in router.md. 2. Copy the matching HTML template. 3. Copy templates/visualize-theme.css into the output assets folder. 4. Replace every VISUALIZE: marker with factual content or remove the unused block. 5. Add Mermaid only where it clarifies a process, timeline, state, dependency, or recommendation. 6. Run the checks in verification.md.