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.
• 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.

Content Patterns

Use these blocks only when the source supports them. Keep labels factual and compact. Every block should either summarize source-backed content, clarify a relationship, or expose a meaningful gap.

Source Header

• Use when: every visualization needs traceability.
• Omit when: never omit completely; reduce to the minimum available metadata if the source is sparse.
• Minimum content: title, source path or source label, source type, generated timestamp, and any explicit created or updated metadata present in the source.

Section Map

• Use when: the source has headings, chapters, phases, or a hierarchy the reader needs to navigate.
• Omit when: the source is short enough that a map would just repeat the full content.
• Minimum content: top-level sections plus one factual note per section only when the source gives enough substance.

Key Takeaways

• Use when: the source contains several important facts, shifts, risks, or outcomes that benefit from a fast scan.
• Omit when: the page is already dominated by a richer structured block that makes a takeaway list redundant.
• Minimum content: three source-backed points unless the source is truly smaller. Do not invent impact, urgency, or priority.

Phase Timeline

• Use when: a plan or procedural source has ordered phases, milestones, or state changes.
• Omit when: there is no meaningful sequence beyond one isolated step.
• Minimum content: phase name, current status, objective, touched files or scope cue when present, and verification command or checkpoint when present. Preserve [ ], [-], and [x] states.

Task Checklist

• Use when: the source already defines tasks, substeps, or acceptance checklists.
• Omit when: a checklist would duplicate a timeline or section map without adding actionable detail.
• Minimum content: source task wording grouped by phase or section, with statuses preserved when present.

Dependency Map

• Use when: the source names file relationships, upstream or downstream dependencies, prerequisites, or sequencing constraints.
• Omit when: dependencies are obvious from a simple linear phase list and a dedicated map would add noise.
• Minimum content: at least two connected entities, files, systems, or phases with a factual relationship label.

Risk Matrix

• Use when: the source lists risks, blockers, mitigations, constraints, or open questions with consequences.
• Omit when: there are no meaningful risks and a warning block covers the only gap.
• Minimum content: risk or blocker, trigger or condition, impact if present, and mitigation or missing-mitigation note.

Decision Trail

• Use when: the source includes decisions, rationale, trade-offs, or a sequence of approved choices.
• Omit when: the source only contains one small decision that fits naturally inside another block.
• Minimum content: the decision, supporting rationale or source cue, and any resulting consequence or next action when present.

Recommendation Block

• Use when: the source asks for next steps, follow-ups, critiques, or improvement options.
• Omit when: the source is purely descriptive and no supported recommendation can be made.
• Minimum content: each recommendation must cite the source fact, risk, blocker, or missing evidence that supports it.

Source Audit Gap Block

• Use when: the visualization should highlight missing evidence, missing verification, unresolved ownership, empty plan sections, or unsupported claims.
• Omit when: there are no meaningful gaps worth surfacing.
• Minimum content: the missing item, why it matters, and the local source context where the gap appeared.

Assumption Block

• Use when: output location, title, ordering, grouping, or interpretation is inferred.
• Omit when: there are no material inferences.
• Minimum content: clearly labeled assumption plus the reason the assumption was necessary.

Warning Block

• Use when: files are missing, the source is ambiguous, verification could not be completed, Mermaid was unsuitable, or the page intentionally pruned unsupported panels.
• Omit when: the issue is already captured more precisely in a source audit gap or assumption block.
• Minimum content: the issue, its effect on the output, and what was done instead.

Mermaid Recipes

Prefer several small diagrams over one dense diagram. Keep labels factual and short. Use Mermaid only when it reveals flow, timing, dependency, state, or interaction that the prose alone would make harder to inspect. 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.

Do not use Mermaid just to mirror the source heading tree, restate a bullet list, or decorate a panel that already reads clearly without a diagram.

Template Router

Choose the smallest template that fits the requested source and planned block set.

Routes

Fallbacks

• Mixed inputs: use the dominant source type and add a source list, decision trail, dependency map, or source-audit gap block only when the combined sources support it.
• Review or source-audit requests: keep the dominant source template, but route the page toward warnings, source-audit gaps, decisions, risks, and recommendation evidence instead of forcing a neutral summary.
• 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.
• Active plan or brainstorm context: prefer the active artifact folder over docs/.visualizations/.
• 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 outputs always use ./visualize-assets/visualize-theme.css.
• Brainstorm and active artifact folder outputs always use ./visualize-assets/visualize-theme.css.
• Document outputs must link ./<source-base>.visualize-assets/visualize-theme.css.
• Source-less context outputs under docs/.visualizations/<slug>-YYMMDD-HHmm/ must link ./visualize-assets/visualize-theme.css.
• Copy the CSS into the adjacent generated assets folder before writing HTML, and update any template default path that does not already match the chosen output contract.

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.
• CSS link path matches the chosen output contract (visualize-assets/, <source-base>.visualize-assets/, or visualize-YYMMDD-HHmm-<slug>.visualize-assets/).
• 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.
• Mermaid is omitted when it would only mirror headings, repeat nearby prose, or add decorative noise.
• Source metadata is visible.
• Each major panel has enough source-backed content to justify its presence, or the panel is removed or converted into a warning or gap block.
• No empty panels, placeholder prose, or leftover instruction comments remain in the delivered HTML.
• No repeated summary content appears across hero text, takeaways, and panel bodies unless repetition is clearly purposeful.
• Recommendations cite a supporting fact, risk, blocker, or missing evidence from the source.
• Review or critique outputs surface the relevant gaps, risks, decisions, or unsupported claims instead of defaulting to a neutral summary.
• Source-derived text is HTML-escaped unless it is intentional generated markup authored by the agent.
• Low-value boilerplate is pruned; sections that add nothing beyond headings or file names are removed.
• 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 a content-first workflow for documentation visualization. The output should make source structure easier to inspect without changing the source material, and layout choices come only after the useful source-backed content is known.

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 Inventory Checklist

Build a compact inventory before choosing a template block layout. Capture only source-backed content:

• Title or inferred title
• Source path
• Created or updated metadata when present
• Section or hierarchy map
• Entities, files, systems, or actors named in the source
• Phases, tasks, statuses, owners, and dependencies when present
• Decisions, rationale, and recommendation evidence
• Risks, mitigations, blockers, and open questions
• Verification steps, expected results, and acceptance criteria
• Missing evidence, missing verification, or source gaps that the visualization should expose
• Explicit assumptions only when the source leaves unavoidable gaps

Block Selection Rules

• Treat templates as shells, not required panel lists.
• Include a block only when it adds source-backed value, clarifies a relationship, or exposes a meaningful gap.
• Omit blocks that would be empty, repeat nearby content, or only restate headings.
• Convert missing but important content into a warning or gap block instead of silently inventing filler.
• Escape source-derived text before inserting it into HTML unless the text is intentional generated markup authored by the agent.

Composition Steps

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