ascii-guard

name	ascii-guard
description	Fix and validate ASCII box-drawing diagram alignment in markdown files. Use when creating architecture diagrams, checking diagram alignment, fixing ASCII art, or before committing documentation with diagrams.

ASCII Guard

Fix and validate alignment issues in ASCII box-drawing diagrams in markdown code blocks.

What It Does

ASCII boxes drawn with Unicode characters (┌┐└┘│─ and ╔╗╚╝║═) often have misaligned right borders because content lines are wider or narrower than the border. ASCII Guard detects these mismatches and fixes them automatically by adjusting borders and padding content to a consistent width.

Before

┌──────────────────────────────┐
│   Context Personalization     │   ← right │ doesn't align with ┐
│   (welcome msg, ICP,          │
└──────────────┬───────────────┘   ← ┘ doesn't align with ┐ either

After

┌───────────────────────────────┐
│   Context Personalization     │   ← all right borders aligned
│   (welcome msg, ICP,          │
└──────────────┬────────────────┘

How to Run

The script is at: scripts/ascii_guard.py

It has zero dependencies (pure Python 3, stdlib only), so run it directly:

Fix files in-place (default)

python3 ${SKILL_DIR}/scripts/ascii_guard.py <file.md>
python3 ${SKILL_DIR}/scripts/ascii_guard.py docs/

Check only (report issues, no modifications)

python3 ${SKILL_DIR}/scripts/ascii_guard.py --check <file.md>

Preview changes as unified diff

python3 ${SKILL_DIR}/scripts/ascii_guard.py --diff <file.md>

Multiple files or directories

python3 ${SKILL_DIR}/scripts/ascii_guard.py docs/*.md README.md
python3 ${SKILL_DIR}/scripts/ascii_guard.py docs/    # recursively finds *.md

Verbose mode (shows box counts per file)

python3 ${SKILL_DIR}/scripts/ascii_guard.py -v <file.md>

When to Use This Skill

Invoke when:

• Creating or editing ASCII architecture diagrams in markdown
• User mentions "ASCII alignment", "diagram alignment", "box drawing", or "fix ascii"
• Before committing docs with box-drawing diagrams
• After generating or editing flowcharts in code blocks
• When boxes look misaligned in rendered markdown

How It Works

1. Finds markdown code blocks (between ``` markers)
2. Detects boxes by matching ┌...┐ top borders with └...┘ bottom borders at the same column
3. For each box, calculates the maximum inner width across all lines (borders + content)
4. Extends narrower borders by adding ─ to the right (preserving ┬/┴ connector positions)
5. Pads narrower content lines with trailing spaces
6. Processes side-by-side boxes right-to-left to avoid column shifting

Supported Characters

Single-Line

Corners: ┌ ┐ └ ┘
Lines:   ─ │
T-joins: ├ ┤ ┬ ┴

Double-Line

Corners: ╔ ╗ ╚ ╝
Lines:   ═ ║
T-joins: ╠ ╣ ╦ ╩

Exit Codes

Code	Meaning
0	All boxes aligned (or fixed)
1	Issues found (with --check/--diff)

What It Preserves

• Annotations after box borders (<-- NEW, <-- UPDATED)
• Vertical connector positions (┬/┴ stay at same column)
• Side-by-side box layout
• Content that's already at max width (unchanged)
• Everything outside code blocks (untouched)