ascii-visual

ascii-visual

Overview

When asked to visualize a topic in ASCII, produce a Unicode box-drawing diagram inside a markdown fenced code block. The diagram is the deliverable — surrounding prose introduces it and (sometimes) interprets it, but the visual carries the explanation.

Core principle: the visual is more valuable than prose precisely because drawing it forces commitment to concrete claims — real file paths, real function names, real numbers. If you can't fill in a specific value, the topic isn't understood well enough to visualize yet — go find the answer first.

When to use

Use when the user asks for:

• "ASCII visual of X" / "ascii art of X" / "ascii diagram of X"
• "Draw / visualize / show me a picture of X"
• "Diagram of X" / "make a visual of X" (where X is a system, flow, decision, comparison, or relationship)
• Speech-to-text variant: "a s c i i visual / art / diagram" (spaces)
• "X vs Y" comparisons that benefit from a side-by-side or sequential picture

Use proactively when a complex flow or comparison just landed in prose and the reader would parse it faster as a diagram.

Do NOT use for:

• Numeric data plots — use a real chart (matplotlib, etc.) or table
• Slack client messages — use /sprint-notify or /nap-slack (they have their own visual patterns)
• PDFs / external deliverables — use /gen-pdf (renders proper graphics)
• Requests that explicitly want SVG, Mermaid, PNG, or image output
• Trivially simple flows (A → B → C) — a sentence is fine

The character palette

Use	Characters
Single-line component boxes	┌ ─ ┐ │ └ ┘ ├ ┤ ┬ ┴ ┼
Double-line header/section boxes	╔ ═ ╗ ║ ╚ ╝ ╠ ╣ ╦ ╩ ╬
Arrows (flow direction)	──> / <── / ▼ / ▲ / ↓ / ← / →
Branches / forks	─┬─ (split) / ─┴─ (join) / ┼ (cross)
Status glyphs	✓ (ok) / ✗ (fail) / ╳ (blocked) / • (bullet)

Avoid raw ASCII (-, |, +) — they don't align cleanly and look amateur. Mobile Slack and some terminals render box-drawing chars better than -+|.

The 10 rules (apply in order)

1. Wrap in a fenced code block so monospace renders. Never inline a multi-line visual in prose.
2. Headline with a double-line box stating what's being visualized: ╔══ REAL DM SMOKE TEST ══╗. Reader knows the topic from glance #1.
3. Number the steps inline: (1) send DM, (2) validate secret, (3) route to FAQ. The diagram doubles as a runbook.
4. Label every arrow with 1–3 words of what it conveys: ── boto3 invoke ──> not bare ─►.
5. Specificity rule — no placeholders. Real file paths (agents/inbound_webhook/handler.py), real function names (format_reply_for_channel), real env var names (BOOKING_LAMBDA_NAME), real Lambda names (naptic-platform-aer-pilates-prod-faq-agent), real numbers (0.75s pause, ≤ 400 chars, cap at 3 chunks). If you can't fill in a real value, stop and find it.
6. Group related details inside the box. When a component does several things, list them as •-bulleted items inside its box. Add a sub-title row underneath the box border if it helps reading.
7. Width target ≤ 70 chars. GitHub markdown renders code blocks at a fixed-ish width; Slack reflows past ~65 on mobile. Keep boxes narrower than that.
8. Two-diagram pattern for comparisons. "X vs Y" or "before vs after" = two consecutive diagrams in the SAME visual style, then a markdown comparison table underneath. Table is regular markdown, not ASCII — readers can sort/copy it.
9. Trail with an evidence section. For technical flows, list the CloudWatch log shapes, DDB row shapes, HTTP response shapes — anything that converts the visual into observable signals you can grep for. One short paragraph or bulleted list.
10. One visual per concept. Don't stuff multiple unrelated flows into a single mega-diagram. Two diagrams beat one busy one.

Canonical example (FAQ → Booking handoff)

                ╔══════════════════════════════════════════╗
                ║  CUSTOMER MESSAGE (IG DM / email)        ║
                ║  e.g. "what classes do you have tonight?"║
                ╚════════════════════╤═════════════════════╝
                                     │
                                     ▼
              ┌──────────────────────────────────────────┐
              │           FAQ AGENT  (Sonnet 4.6)        │
              │   unified inbound responder              │
              │   tools:                                 │
              │     • retrieve_knowledge   (KB walk)     │
              │     • send_email                         │
              │     • handoff_to_booking   ← NEW (#487)  │
              └──────┬──────────────────┬────────────────┘
                     │                  │
        ┌────────────┴───────┐   ┌──────┴──────────────────┐
        │  FAQ-OWNED         │   │  HANDOFF-OWNED          │
        │  (KB walk only)    │   │  (boto3 lambda invoke)  │
        │  • pricing         │   │  • "tonight's classes?" │
        │  • intro offers    │   │  • "is Saturday Aerial  │
        │  • membership      │   │     11am open?"         │
        │  • refunds         │   │  • "who teaches X?"     │
        │  • brand questions │   │  • availability checks  │
        └────────────────────┘   └──────────┬──────────────┘
                                            │ boto3.invoke(
                                            │   FunctionName=
                                            │     BOOKING_LAMBDA_NAME)
                                            ▼
                              ┌─────────────────────────────┐
                              │  BOOKING AGENT  (Haiku 4.5) │
                              │  READ-ONLY, Phase 1         │
                              │  • lookup_schedule          │
                              │  • lookup_class             │
                              │  • lookup_availability      │
                              └─────────────────────────────┘

ROLLBACK:  BOOKING_HANDOFF_DISABLED=1  →  tool returns ""
           FAQ Rule 12 triggers graceful defer.

Evidence to look for (the trail):

• manychat_reply_delivered { chunk_count: > 1 } in CloudWatch
• booking_handoff_succeeded { response_chars: > 0 }
• Single outreach-history DDB row with body_text joined by ---chunk-split---

Common mistakes

Mistake	Fix
Using - `	+` instead of box-drawing chars
Placeholder names (<your-lambda-name>, TODO, XXX)	Stop. Find the real value. The skill is wasted if the diagram lies.
Bare arrows with no labels (─► alone)	Label every arrow with what it conveys: ── boto3 invoke ──>.
One huge mega-diagram covering 3 unrelated flows	Split into 2–3 separate diagrams with their own headline boxes.
Diagram without an evidence trail	Add a short bulleted list of CloudWatch log shapes / DDB rows / HTTP responses to verify.
Inlining a multi-line visual in prose (no code fence)	Wrap in triple-backticks. Markdown collapses whitespace; the visual breaks.
Width > 75 chars	Mobile/Slack wraps unpredictably past 65–70. Tighten the boxes.

Pattern library by topic type

Topic	Shape
Linear flow (A → B → C → D)	Vertical sequence, ▼ arrows, one box per step
Decision tree	─┬─ fork, condition labels on each branch
System architecture	Stacked boxes, sub-boxes for components inside, arrows showing data flow
Agent topology	One box per agent, arrows showing handoff direction, group similar agents in a parent frame
Before/after	Two diagrams stacked or side-by-side, identical box shapes, table beneath comparing rows
Pipeline (build/deploy)	Horizontal sequence with ──> arrows; each stage's gate condition labeled
Timeline	Calendar squares or a ├──┼──┼──┤ horizontal axis with date labels
Topology / relationships	Hub-and-spoke or graph with ─┬─ joins

For Slack-specific client comms or sprint-notify patterns (calendar grid, status line, big-number callout, tab/nav), see ~/.claude/skills/sprint-notify/SKILL.md — different deliverable channel, similar visual idioms.

Workflow

1. Identify the topic shape (linear flow? comparison? architecture? decision?) from the user's request.
2. Confirm you have the real concrete details (file paths, function names, env vars, numbers). If not, find them first.
3. Pick the headline phrasing for the double-line box.
4. Draft the diagram. Iterate on width — tighten boxes until ≤ 70 chars.
5. Add the evidence section (one short bulleted list).
6. For comparisons: draft a second diagram in the same style + a markdown comparison table.
7. Surround with 1–3 sentences of prose introducing what the visual shows and (only when needed) interpreting it.

Related memories + skills

• [[feedback-nap-slack-ascii-visual]] — same rule applied to @nap Slack client comms (width target 58–62 chars for mobile).
• [[feedback-sprint-recap-notify-ascii]] — pairs /sprint-recap + /sprint-notify, both must include an ASCII visual.
• ~/.claude/skills/sprint-notify/SKILL.md — Slack-specific ASCII pattern library (calendar / status line / big-number / tab nav).
• /gen-pdf — when the deliverable needs to render to PDF, use that instead.
• /nap-slack — when the deliverable goes to a Slack client channel, use that instead.