show-me

Use this when

The user needs to understand the current topic visually, such as an algorithm, runtime path, UI structure, file responsibilities, proposed change, or a dense concept.

When applying this runbook, lead directly with the visual and keep accompanying prose brief. Choose the smallest view that makes the key point clear.

Steps

1. Identify the point the visual must explain

Use the current conversation to determine what the user is trying to understand or decide. Inspect relevant code or artifacts when the visual describes actual implementation. Use real names, labels, paths, and data from that context.

Keep only the calls, files, props, states, and ownership or module boundaries needed to answer the question or compare the options under discussion. Avoid expanding into a complete architecture overview unless that is the question.

2. Choose a format that fits the topic

Use one format, or a few complementary views when each adds necessary information. Do not use every format by default.

• Pseudocode: Logic, an algorithm, a branch, or a sequence of decisions.
• Call tree: Runtime calls and the order or nesting of execution.
• Component tree: UI structure, with relevant state hooks and module boundaries.
• Shallow file tree: File responsibilities or the shape of a broad refactor.
• Mermaid: Interactions between components, control flow, or data flow.
• Diff: A change to a shape the user already understands. Match the structure to the topic.
• Complete block: A mostly new shape, necessary ownership or ordering context, or a copyable target.
• Focused HTML: A visual UI, layout, state comparison, or concept too dense for Mermaid.

3. Build the selected view

The examples below illustrate the formats. Replace their names and structure with the actual topic when using the runbook.

For logic, express the meaningful branches without incidental implementation details:

on(save)
  if content is unchanged
    return cached result
  write new content
  return fresh result

For runtime flow, show the calls whose ownership or ordering matters:

submitForm
  createSession
    persistPrompt
    launchAgent
  navigateToSession

For UI structure, include relevant state and module boundaries. Annotate components with their actual file paths when those paths explain ownership:

<SessionPage> (page module)
  useSessionEvents()
  <SessionToolbar>
    <RunSkillButton> (shared UI module)

For file responsibilities, keep the tree shallow and add short responsibility comments:

src/
├── commands/       # parses user actions
├── sessions/       # owns session state
└── transport/      # sends API requests

For interaction or data flow, show participants and the messages relevant to the question:

sequenceDiagram
    participant User
    participant UI
    participant Service
    User->>UI: choose command
    UI->>Service: send expanded prompt
    Service-->>UI: stream result

4. Show changes in the same shape as the subject

Use a diff when the point is what changes and the surrounding shape already exists. Keep enough unchanged context to locate the change.

For a component change:

 <SessionPage>
   useSessionEvents()
   <SessionToolbar>
+    <RunSkillButton />
   <SessionTimeline>
+    <SkillResultCard />

For a file-layout change:

 src/
 ├── commands/
+│   └── show-me.ts       # expands the command
 ├── sessions/
-└── transport.ts
+└── transport/
+    ├── client.ts
+    └── stream.ts

For a call-tree or call-stack change:

 submitForm
   createSession
     persistPrompt
+    expandSkillMention
     launchAgent
-  navigateToSession
+  navigateToSession
+    subscribeToEvents

For a state or control-flow change:

 on(save)
-  write content
+  if content is unchanged
+    return cached result
+  write new content
+  invalidate cache

Show the whole block when most of it is new, omitted context would hide ownership or order, or the user needs a copyable target shape:

function expandSkill(command: string): string {
  const skillName = command.slice(1)
  return `use the ${skillName} skill`
}

5. Use HTML when it makes the point clearer

For a visual UI, layout, state comparison, or dense concept, write one focused HTML file. Choose a diagram, infographic, or short slide deck according to the point being explained.

Match the product's colors, type, spacing, and components when a product context exists. Use real labels and data from the discussion, and make the view work on desktop and mobile. Keep it focused on the same question rather than building an unrelated dashboard or presentation.

Give the file a descriptive name such as show-me-<description>.html. Preview it and check that its labels, layout, and comparisons remain readable at the relevant sizes. Then open or publish it with the environment's supported browser or inline display so the user can actually see it. A saved file alone does not deliver the visual.

6. Deliver the visual with minimal text

Place each visual next to the short text it supports. Skip the preamble. Explain only what the visual needs to be understood, and distinguish a proposed shape from the current implementation when that distinction matters.

Check that the visual answers the current question, preserves meaningful ownership and order, and uses accurate labels. Remove details or extra views that do not help the user understand or decide.

Done when

• The visual directly explains the current topic or options under discussion.
• Its format fits the point, and only necessary structure, state, or boundaries are included.
• Actual implementation views use names and paths checked against the relevant artifacts.
• Diffs retain useful context, and complete blocks are shown when context or copyability requires them.
• Any HTML view matches the relevant product context, works on desktop and mobile, and is opened or displayed for the user.
• Each visual sits beside brief supporting text, with no preamble or unnecessary views.