code-option-comparison

Code Option Comparison

Why this skill exists

When a user is choosing between distinct ways to do something — "Redis or Postgres LISTEN/NOTIFY for pubsub?", "give me 4 onboarding flow designs", "compare polling vs streaming vs websocket" — the right artifact is not a long narrative. It's a grid: N columns, the same sub-sections in each, scannable tradeoffs, ending in a comparison matrix and a recommendation. This skill produces that grid as a single self-contained HTML file.

When to use

Trigger phrases: "compare N approaches", "side-by-side comparison", "give me 4 different ways to X", "lay them out so I can compare", "show me the tradeoffs between X and Y and Z."

Inputs: a choice point the user faces (a design decision, implementation strategy, schema shape, algorithm) — with the options either enumerated by the user or generated by you on request.

Output: one self-contained HTML file, typically docs/comparisons/<topic>.html.

When NOT to use

• One topic with a narrative arc → software-visual-explainer.
• PR review → software-visual-explainer in PR mode.
• Throwaway interactive editors → prompt from scratch.
• More than ~6 options → grids get unscannable. Pick a top 6 and note the also-rans, or write a narrative.

Process

1. Enumerate the options. Work from the user's list, or generate N distinct options yourself — explicitly vary the tradeoff each makes (cost vs latency, simplicity vs flexibility, …). Each must be distinct enough that the comparison is meaningful.
2. Define the comparison axes — the same 4–8 questions you'll answer for every option (complexity, maintenance cost, latency, failure modes, team familiarity, lock-in, observability). Pick axes that actually differentiate.
3. Verify against the codebase if any option is "what we have today" or a small extension of it — real symbols, real method names, same rule as software-visual-explainer.
4. Draft from templates/template.html, filling in N column blocks per references/column-shape.md.
5. Self-review. Every column answers every axis; the matrix shows all options against all axes; no empty cells.
6. Offer to review. Ask the user to spot-check, noting which option you'd recommend and why — the reader is choosing, not you. Run references/verification.md first.

Reference map

This SKILL.md is the orchestrator. Detail lives in the reference files:

For…	Read
Column sub-sections, the comparison matrix, recommendation, grid layout, copy buttons	references/column-shape.md
The pre-completion checklist (content, build, a11y, print)	references/verification.md
The HTML skeleton to start from	templates/template.html

Rendering (CDN, no build)

templates/template.html is fully self-contained: it embeds the shared core and loads Mermaid + Prism from a CDN. There is no build step. Write .mermaid blocks and <pre><code class="language-X">, replace {{LANGUAGE}} in the Prism <script> tag with the language(s) used, and open the file in a browser — Mermaid renders the diagrams and Prism highlights the code. Nothing to install, no Node. (The page needs a network connection to reach the CDN; it is not offline-self-contained.)

Do not fork the palette. The template's <style>/<script> are an inline copy of visual-explainer-core's core.css/core.js. Never hand-edit the theme in one template — change the canonical core.css/core.js and re-sync (see that skill). Add only comparison-specific components in the template's own <style> block.

Output file location

Default docs/comparisons/<topic>.html; create the directory if needed. Topic name kebab-case.