takazudo/ascii-circuit-diagram-creator

ASCII Circuit Diagram Creator

Creates clear, unambiguous ASCII circuit diagrams through an iterative generate-validate-fix workflow.

Quick Start Workflow

A. Create connection list - Write explicit text connections (which pin → which pin) B. Generate ASCII diagram - Create circuit that satisfies ALL connections C. Preview - Render in monospace font, capture as image D. Confirm - Check for rule violations

• If violations found: Return to B with fixes
• If clean: Proceed to E

E. Complete - Deliver both connection list AND ASCII diagram

Core Principles

Start with connections, not the diagram - The connection list is the specification. The ASCII diagram must satisfy every connection in the list.

Connection list is a deliverable - Always provide both:

1. Connection list (explicit, unambiguous)
2. ASCII diagram (visual representation)

Preview is mandatory - Label crossings and alignment issues are invisible in plain text but obvious in monospace rendering.

Follow the golden rules - See references/golden-rules.md for complete list:

1. Never cross lines without junctions
2. Never cross lines over text labels
3. Use label notation for distant connections - Use "GND" labels frequently to avoid cluttered diagrams (many components connect to GND)
4. Show parallel components as vertical drops
5. Maintain consistent column alignment
6. Use Unicode characters - ┌ ┐ └ ┘ ├ ┤ ┬ ┴ ─ │ for lines/junctions, → ← for arrows
7. Use boxes to identify components - Each component gets its own box with proper padding (at least 1 space on each side)
8. Separate complicated layouts - When circuit details get complex, create a separate diagram block
9. Avoid ambiguous ASCII - Don't use + for junctions (ambiguous direction)
10. No flying lines - Vertical lines must maintain exact column alignment throughout
11. Preview AND analyze carefully - Looking at screenshots without tracing signal paths is worthless

Step-by-Step Process

Step A: Create Connection List

Write explicit text connections showing which pin connects to which:

Format:

Connections:
- Component1 pin X → Component2 pin Y
- Component2 pin Z → Component3
- Component3 → GND (parallel capacitor)

Example (Buck Converter):

Connections:
- +15V input → U2 (LM2596S) pin 5 (VIN)
- +15V input → C5 (100µF) → GND
- U2 pin 3 (ON) → +15V (always enabled)
- U2 pin 4 (VOUT) → Switching node
- Switching node → L1 (100µH) → +13.5V Output
- Switching node → D1 (SS34 Schottky cathode)
- D1 (SS34 Schottky anode) → GND
- +13.5V Output → R1 (10kΩ) → Tap point
- Tap point → R2 (1kΩ) → GND
- U2 pin 2 (FB) → Tap point
- +13.5V Output → C3 (470µF) → GND
- U2 pin 1 (GND) → GND

Key points:

• Every component connection must be listed
• Show pin numbers for ICs
• Indicate parallel vs. series connections
• Specify component values
• This list serves as the specification for the diagram

Step B: Generate ASCII Diagram

Create the ASCII diagram that satisfies ALL connections from Step A:

Layout strategy:

• Separate functional blocks - Break complex circuits into labeled sections (IC, switching node, input caps, feedback network)
• Branch right, then down - Use └─── to create branches that extend right first, then go vertical
• Main flow horizontal, branches vertical - Keep signal flow left-to-right, use vertical lines for branches to GND or parallel components
• Place IC in center of its section
• Input components on left or in separate section
• Output components on right or in separate section
• Route flyback diodes UPWARD to avoid label crossings (or use separate section)
• Use Unicode characters throughout: ├ ┤ ┬ ┴ ─ │ ┌ ┐ └ ┘ for lines/junctions, → ← for arrows
• Avoid ASCII + for junctions - it's ambiguous about connection direction
• Apply label notation for distant connections (FB ├2─→ Tap)
• Ensure vertical lines maintain exact column alignment (no flying lines)

Component representation:

• ICs: Show pin numbers and names
• Passives: Include values (10µF, 5.1kΩ)
• Voltages: Label at each stage
• Parallel components: Draw as vertical drops to GND

Best practice: Parallel capacitors (filter pairs):

Power ──┬────────────────┬─── To IC
        │                │
       C1               C2
      100nF            470µF
     ceramic        electrolytic
     (CLOSE!)        (farther)
        │                │
       GND              GND

• T-junction (┬) at TOP on power rail
• Capacitor labels in middle of vertical lines
• Clear vertical drops to GND
• Left-to-right order: Ceramic (CLOSE to IC) on LEFT, electrolytic (farther) on RIGHT
• Shows physical placement hints

Separated section example (recommended for complex circuits):

IC Section:
                    ┌──────────────┐
Input ──────────────┤1 VIN     OUT 2├───── Signal Node
                    │              │
                 ┌──┤3 GND      FB 4├──── FB Tap
                 │  └──────────────┘
                GND

Switching Node Section:
                                 ┌─────────────┐
Signal Node ────────┬────────────┤ L1 (100µH)  ├──────────── Output
                    │            └─────────────┘
                    │
                    └─── D1 (Schottky)
                         Cathode
                            │
                         Anode
                            │
                           GND

Input Filter Section:
Input ───┬─── To IC
         │
         ├─ C1 (100µF)
         │    │
         │   GND
         │
         └─ C2 (100nF)
              │
             GND

Key benefits of separated sections:

• No line crossings between different functional blocks
• Crystal clear component grouping
• Easy to trace signal paths
• Simple to add/modify individual sections
• Branches use └─── (right first, then down) or ┬ (split, then vertical)

Critical: Verify every connection from Step A is represented in the diagram.

Step C: Preview

Run the preview script to render in monospace font and capture as image:

bash $HOME/.claude/skills/ascii-circuit-diagram-creator/scripts/preview_diagram.sh <diagram-text-or-file>

The preview creates an "almost empty HTML" with monospace font styling and captures the result using headless browser. This reveals issues invisible in plain text:

• Lines crossing labels
• Ambiguous junctions
• Incorrect component leg counts
• Junction topology errors

Step D: Confirm

CRITICAL: Check the preview image for rule violations by tracing each signal path and inspecting vertical line alignment.

Simply looking at the screenshot is not enough - you must:

1. Trace each signal from source to destination
2. Verify junctions - does each ├ ┤ ┬ ┴ connect the correct signals?
3. Check for false junctions - do any signals appear connected that shouldn't be?
4. Verify topology matches the connection list from Step A
5. Inspect vertical line alignment - Look for "broken" or "floating" lines where alignment is off by even 1 character

If ANY violations found, return to Step B with fixes.

Preview phase is critical for detecting:

• Lines crossing labels (invisible in plain text, obvious in preview)
• False junctions where signals appear connected but shouldn't be
• Box padding issues where text touches borders
• Incorrect component leg counts

Check against golden rules (see references/golden-rules.md):

Rule 1: Line crossings without junctions

• Look for ┼ symbols (usually wrong)
• Check if non-connected lines cross

Rule 2: Lines crossing labels

• Look for vertical/horizontal lines passing over text
• Most common issue: switching node line crossing "Tap" or "GND" labels

Rule 3: Disconnected components

• Verify all components connect to appropriate nodes
• Check input capacitors connect to power rails
• Ensure feedback networks connect to correct pins

Rule 4: Incorrect polarity

• Diodes: Cathode to higher potential, anode to lower
• Buck converter: Flyback diode cathode to switching node, anode to GND

Rule 5: Unclear parallel/series connections

• Filter capacitors should be vertical drops to GND
• Should NOT appear in series with signal path

Common fixes:

Fix: Line crossing label

• Solution A: Route in opposite direction (if going down crosses labels, route up)
• Solution B: Remove intermediate label
• Solution C: Use wider spacing to route around

Example:

Before (crosses labels):    After (routes upward):
VOUT ├4───┬─→ L1            D1 ← Routes UP
          │                    │
          │ (crosses)      VOUT ├4───┴─→ L1
       D1 ↓

Fix: Disconnected component

• Add connection using appropriate junction (┬ ├ ┤ ┴)
• Ensure vertical line from power rail reaches component

Fix: Inverted polarity

• Swap component orientation
• For diodes: cathode (top) to higher potential, anode (bottom) to GND

Fix: Ambiguous parallel/series

• Redraw parallel components as vertical drops
• Use ├─→ to branch from main signal path

Iteration: Repeat B → C → D until all rules satisfied. Usually 2-3 iterations sufficient.

Step E: Complete

Once all rules satisfied, deliver both:

1. Connection list (from Step A)
2. ASCII diagram (final validated version)

Optionally explain key connections or design choices if complex.

Common Patterns

See references/examples.md for detailed examples of:

• Buck converter (LM2596S-ADJ)
• Common mistakes and fixes
• Before/after comparisons

Validation Checklist

Before finalizing, verify:

• [ ] No line crossings without explicit junctions
• [ ] No lines crossing over text labels
• [ ] All components properly connected (no floating components)
• [ ] Parallel components shown as vertical drops to GND
• [ ] Diode polarity correct (cathode/anode orientation)
• [ ] Unicode box-drawing characters used (┌ ┐ └ ┘ ├ ┤ ┬ ┴ ─ │ and → ← arrows, no ambiguous ASCII + junctions)
• [ ] No flying/disconnected lines (vertical lines maintain column alignment)
• [ ] Consistent column alignment (no sliding vertical bars)
• [ ] Label notation used for distant connections
• [ ] Preview verified in monospace rendering

When to Use This Skill

Use this skill when:

• User requests ASCII/text-format circuit diagrams
• Creating technical documentation with embedded circuits
• Need to ensure diagram clarity and correctness
• Converting schematic to ASCII representation
• Building circuit diagrams for code comments or markdown docs

Key indicator: User mentions "ASCII circuit," "text diagram," "schematic in text," or shows existing ASCII circuit that needs fixing.

Tool Integration

Preview tool: Uses the headless-browser skill (external dependency — installed from Takazudo/zudo-test-wisdom, not part of this repo) to render diagrams in monospace font and capture screenshots for validation. This is critical for catching issues before finalizing. scripts/preview_diagram.sh still writes the HTML preview and degrades with a warning instead of failing if headless-browser isn't installed.

References:

• references/golden-rules.md - Complete rule specification
• references/examples.md - Good/bad examples and fixes