show-me

Show Me

Don't tell me. Show me.

show-me turns verification, review, explanation, documentation, demos, or subsystem understanding into a polished local HTML portfolio/deck when chat or terminal output is the wrong medium.

Use this for:

• proving a change works with evidence
• walking through code or architecture visually
• reviewing a diff, subsystem, or document set
• explaining a workflow, data flow, or decision tree
• building visual documentation from sourced facts
• showing UI, CLI, browser, or native-app behavior with media and logs

Do not use this for:

• automatic verification inside verify, ship-it, or other flows in v1
• committing generated decks unless a future workflow explicitly allows it
• hiding failed checks behind a polished report
• generating unsourced explanations that look authoritative

`show-me` is manual/user-requested in v1. Do not auto-run it from another Beislið skill. If another workflow thinks a visual deck would help, suggest it and wait for the user to ask.

Output modes

Classify the deck before gathering evidence. Use one mode, or mixed when multiple apply. Also choose or infer a presentation: visual-deck for explanatory understanding decks, evidence-deck for proof/demo decks, and report for review/docs/code walkthroughs.

• verification — prove claims with command/media evidence
• review — inspect work or materials visually
• code-walkthrough — explain diffs, file roles, tests, risks, and rationale
• ui-demo — show UI behavior through screenshots, videos, GIFs, and browser evidence
• cli-demo — show command behavior through logs, transcripts, or terminal recordings
• docs — visualize rendered docs, validation output, and documentation structure
• understanding — explain a subsystem/topic with sourced facts and interpretation
• mixed — combine modes for broad changes

Status values:

• PASS — evidence supports the stated claim
• FAIL — evidence contradicts the claim or a check failed
• INCOMPLETE — some required evidence is missing
• NOT SHOWN — a claim was not demonstrated
• NEEDS CAPTURE — media/evidence tooling was unavailable or capture was deferred
• EXPLANATORY — understanding/documentation deck, not pass/fail verification
• CONFLICTING — sources disagree or evidence points in different directions
• LOW_CONFIDENCE — explanation is plausible but source coverage is weak

Workflow

1. Classify intent

Identify:

• subject: what is being shown
• mode: verification, review, walkthrough, demo, docs, understanding, or mixed
• audience: reviewer, future maintainer, user, or self
• outcome: what the deck should let the human decide

If the user explicitly asked to generate/build/make the deck, proceed after this classification. If the request is ambiguous, propose the mode/outline and ask before generating.

2. Inspect sources

Gather only the context needed for the deck:

• git diff, commits, branch, and plans when verifying or reviewing changes
• relevant source files and tests
• docs or rendered output for docs decks
• URLs, screenshots, videos, logs, or command output supplied by the user
• architecture facts, diagrams, or command outputs needed for understanding decks

Distinguish sourced facts from interpretation. Do not invent rationale; if rationale is inferred, label it as inferred.

3. Choose output root

Default output root:

${BEISLID_STATE_DIR:-~/.local/state/beislid}/show-me/<repo>/<timestamp>/

Repo-local output is allowed only when explicitly requested or configured:

.beislid/show-me/<timestamp>/

Generated decks are local artifacts and should not be committed in v1.

4. Gather evidence

Use available tools opportunistically:

• command logs for tests, builds, lint, docs generation, CLI demos, or inspections
• existing images/videos/GIFs supplied by the user
• screenshots or recordings when tools are available
• rendered docs pages when relevant
• diffs, file-role tables, and code excerpts for code walkthroughs
• diagrams when they clarify the subject

Ask before destructive, mutating, expensive, long-running, or externally visible actions.

If evidence is unavailable, add a visible NOT SHOWN or NEEDS CAPTURE block. Never imply missing evidence exists.

5. Create the artifact

For understanding decks with EXPLANATORY status, bias toward a visual decision deck by default:

• cards over long paragraphs
• side-by-side comparisons over dense tables
• flow diagrams for relationships, lifecycle, and data flow
• decision-tree framing for unresolved product choices
• “what gets saved” panels for backend/data behavior
• PM/reviewer checklist cards for open decisions

Create a local source/evidence directory. Current HTML rendering assumes online access for CDN presentation libraries (marked, DOMPurify, Mermaid, Highlight.js); source JSON, logs, and copied media remain local, and Markdown source is visible as a fallback if libraries fail to load.

show-me/<repo>/<timestamp>/
  index.html
  show-me.json
  manifest.json
  assets/
    images/
    videos/
    gifs/
    diagrams/
  logs/
    commands/

The rendered index.html should be polished and human-reviewable:

• dark portfolio/report style unless the subject calls for another style
• sidebar, sticky nav, or clear table of contents when useful
• high-signal sections/chapters, not necessarily slide-only pages
• summary and status near the top
• cards, tables, callouts, media panels, and readable code/diff blocks
• command logs rendered in terminal-style panels
• provenance and caveats at the end

6. Report results

Return:

• path to index.html
• path to show-me.json
• deck status/verdict
• evidence included
• evidence missing or marked NEEDS CAPTURE
• redactions or media-sensitivity warnings

Do not claim the subject passes unless fresh evidence in the deck supports that claim.

Portable document model

show-me.json should use this shape or a compatible superset:

{
  "title": "string",
  "subtitle": "string",
  "mode": "verification|review|code-walkthrough|ui-demo|cli-demo|docs|understanding|mixed",
  "status": "PASS|FAIL|INCOMPLETE|NOT SHOWN|NEEDS CAPTURE|EXPLANATORY|CONFLICTING|LOW_CONFIDENCE",
  "presentation": "report|visual-deck|evidence-deck",
  "summary": "string",
  "sections": [
    {
      "title": "string",
      "purpose": "string",
      "blocks": []
    }
  ],
  "assets": [],
  "logs": [],
  "provenance": {}
}

Sections are chapters of a portfolio/report. They may look like slides when useful, but long-form sections are preferred for technical walkthroughs.

presentation is optional. Omit it to use the renderer defaults.

Presentation defaults:

• understanding + EXPLANATORY → visual-deck
• verification, cli-demo, ui-demo → evidence-deck
• docs, review, code-walkthrough, mixed → report unless explicitly set

Supported block types and canonical content keys:

• markdown — markdown
• table — columns, rows
• code — code, optional language
• diff — diff
• diagram — diagram, optional language: "mermaid" for Mermaid source; copied SVG assets still use media fields
• command-log
• image
• video
• gif
• callout — text, optional title/tone
• verdict — status, text
• needs-capture
• file-role-table

Pi tooling normalizes common aliases like content, body, and table headers, but generated source should prefer canonical keys.

Evidence requirements

Command evidence must include:

• command
• cwd
• timestamp
• exit status
• relevant stdout/stderr in the deck or linked full log

Assets must include:

• original source path or capture method
• copied asset path
• type
• caption
• hash when practical
• media sensitivity warning if the content may contain private data

Understanding decks must include:

• source files/docs/commands inspected
• citations or file references for factual claims
• a clear split between facts, interpretation, and open questions

Failure decks are valid output. If a check fails, generate the deck with FAIL or INCOMPLETE, include the failure evidence, and add suggested next checks.

Provenance

Record when available:

• timestamp
• cwd
• repo/root
• branch
• commit
• dirty status
• generator/version information
• skill version if known
• agent/model/session metadata if available
• concise task context and rationale notes
• command list and exit codes
• asset hashes
• redactions performed

Do not dump the full chat transcript by default. Include only the context and rationale needed to understand the deck.

Redaction and privacy

Text logs, JSON, and rendered HTML should receive best-effort secret redaction. Note redactions in provenance.

Screenshots, videos, and GIFs may contain sensitive information. Warn about this unless a real redaction tool was used. Do not claim media is redacted unless it is.

Pi tooling note

If Pi show_me_* tools or /show-me commands are available, use them to create, update, capture, and render the deck. Prefer show_me_run_command for command evidence so stdout/stderr, exit status, timestamps, cwd, logs, and redactions are captured consistently. Prefer show_me_add_asset for existing screenshots, videos, GIFs, and diagrams so files are copied into the deck with hashes, provenance, captions, and media sensitivity warnings. Use show_me_capture_browser_screenshot for browser screenshots when Playwright is already available; if it is missing or capture fails, use show_me_add_needs_capture or the helper's generated NEEDS_CAPTURE block instead of pretending evidence exists. If the tools are not available, generate the files manually using the artifact contract above.

Future Pi tooling should accelerate this skill, not replace its behavior.