Docs Visual Enrichment Workflow

Use the docs-visual-enrichment skill when DSA pages need explanatory visuals: diagrams, state transitions, architecture flows, data-structure sketches, or tradeoff maps. The goal is clarity, not decoration. Every image should help a reader understand a concept already taught by the page.

Source of truth

Edit canonical content under content/core-docs/dsa.
Store shared DSA assets under public/images/docs/dsa/<slug>.png. Use public/images/docs/dsa/<section>/<slug>.png only when a section has enough assets to need its own folder.
Link assets with root-relative Markdown paths:

![Specific alt text that explains the diagram.](/images/docs/dsa/<slug>.png)

After edits, run:

npm run docs:sync-dsa
npm run docs:check-dsa

Scan steps

List candidate pages:

rg --files content/core-docs/dsa -g '*.md' -g '*.mdx'

Check existing visual usage:

rg -n '!\\[|<img|/images/docs/' content/core-docs/dsa -g '*.md' -g '*.mdx'
find public/images/docs -type f

Prioritize pages where readers must mentally track:

multiple components or queues
pointer/window movement
heap, stack, trie, graph, or DP state
consistency, retry, cache, sharding, or replication flows
lifecycle, state machine, or failure-path tradeoffs

Skip pages where a visual would only repeat a simple list/table, the page already has a clear current diagram, or the content is too thin to support an accurate image.

Section-by-section steps

Section	What to visualize	Steps
Patterns	The invariant and movement recipe: pointer motion, window expansion/contraction, BFS frontier, DFS undo, heap ordering, DP recurrence shape.	Pick one pattern page, identify the central invariant, create a compact flow/state diagram, place it near `## Diagram`, and verify the existing Mermaid still agrees with the new image.
Topics	Topic-level mental models: how problems in the topic differ, which state object changes, and the progression from easy to hard.	Start with topic index pages before individual problems, add one overview diagram per topic, then use problem-page visuals only when the existing Mermaid is not enough.
Problem pages	Dry runs, state tables, and edge-case branches for high-frequency or high-confusion problems.	Select pages by frequency/confusion, define the exact state transition to show, place the image after the problem’s first conceptual explanation or `## Diagram`, and keep code screenshots out of the docs.
Cheatsheets	Decision trees, complexity comparisons, operation-cost matrices, and language idiom maps.	Convert dense tables only when the diagram improves scanning; keep formulas and exact operation costs in text for copyability.
System design	Request flows, storage paths, cache invalidation, replication, sharding, consistency, backpressure, and failure isolation.	For each HLD/building-block/deep-dive page, choose the main runtime flow, draw components with arrows and failure notes, and place the visual immediately after requirements or the opening model.
LLD and design patterns	Class collaboration, object lifecycle, state transitions, concurrency boundaries, and extension points.	Prefer UML-lite diagrams over full UML; show only classes/interfaces needed to explain the pattern or case study.
Interview prep	Study plans, round loops, STAR story structure, company prep flow, and mock-interview cadence.	Use timelines, checklists, and loop diagrams; avoid company-logo assets or speculative internal process diagrams.
Maintenance docs	Workflows that maintain the corpus: sync, validation, visual enrichment, index checks, and automation plans.	Keep visuals sparse; use flow diagrams only when they reduce onboarding time for future maintainers.

Image brief template

Before generating an asset, write a short brief:

- Page: content/core-docs/dsa/<path>
- Concept: <single idea the visual explains>
- Reader takeaway: <what should be obvious after seeing it>
- Diagram type: <flow | state machine | component map | matrix | timeline>
- Exact labels: <all visible text>
- Asset path: public/images/docs/dsa/<slug>.png
- Placement: <section heading or paragraph after which the image appears>

Review gate

Before finishing a visual pass:

Open every generated image and check for clipped text, misspellings, crowded arrows, weak contrast, and inconsistent spacing.
Confirm every Markdown image link resolves to an existing file.
Confirm the visual teaches the same idea as the surrounding text.
Run npm run docs:sync-dsa.
Run npm run docs:check-dsa.

Reporting checklist

For each completed pass, report:

files scanned
pages updated
assets generated
pages skipped and why
validation commands run