ASCII Diagram Validator
Validate and fix alignment issues in ASCII box-drawing diagrams commonly used in architecture documentation, README files, and code comments.
Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.
Overview
ASCII diagrams using box-drawing characters (─│┌┐└┘├┤┬┴┼ and double-line variants ═║╔╗╚╝╠╣╦╩╬) require precise column alignment. This skill provides:
- Validation script - Detects misaligned characters with file:line:column locations
- Actionable fixes - Specific suggestions for correcting each issue
- Multi-file support - Validate individual files or entire directories
When to Use This Skill
Invoke when:
- Creating or editing ASCII architecture diagrams in markdown
- Reviewing documentation with box-drawing diagrams
- Fixing "diagram looks wrong" complaints
- Before committing docs/ARCHITECTURE.md or similar files
- When user mentions "ASCII alignment", "diagram alignment", or "box drawing"
Supported Characters
Single-Line Box Drawing
Corners: ┌ ┐ └ ┘
Lines: ─ │
T-joins: ├ ┤ ┬ ┴
Cross: ┼
Double-Line Box Drawing
Corners: ╔ ╗ ╚ ╝
Lines: ═ ║
T-joins: ╠ ╣ ╦ ╩
Cross: ╬
Mixed (Double-Single)
╞ ╟ ╤ ╧ ╪ ╫
Quick Start
Validate a Single File
/usr/bin/env bash << 'PREFLIGHT_EOF'
uv run "$(cc-plugin-root doc-tools)/skills/ascii-diagram-validator/scripts/check_ascii_alignment.py" docs/ARCHITECTURE.md
PREFLIGHT_EOF
Validate Multiple Files
/usr/bin/env bash << 'PREFLIGHT_EOF_2'
uv run "$(cc-plugin-root doc-tools)/skills/ascii-diagram-validator/scripts/check_ascii_alignment.py" docs/*.md
PREFLIGHT_EOF_2
Validate Directory
/usr/bin/env bash << 'PREFLIGHT_EOF_3'
uv run "$(cc-plugin-root doc-tools)/skills/ascii-diagram-validator/scripts/check_ascii_alignment.py" docs/
PREFLIGHT_EOF_3
Output Format
The script outputs issues in a compiler-like format for easy navigation:
docs/ARCHITECTURE.md:45:12: error: vertical connector '│' at column 12 has no matching character above
→ Suggestion: Add '│', '├', '┤', '┬', or '┼' at line 44, column 12
docs/ARCHITECTURE.md:67:8: warning: horizontal line '─' at column 8 has no terminator
→ Suggestion: Add '┐', '┘', '┤', '┴', or '┼' to close the line
Severity Levels
| Level | Description |
|---|---|
| error | Broken connections, misaligned verticals |
| warning | Unterminated lines, potential issues |
| info | Style suggestions (optional cleanup) |
Validation Rules
The script checks for:
- Vertical Alignment - Vertical connectors (│║) must align with characters above/below
- Corner Connections - Corners (┌┐└┘╔╗╚╝) must connect properly to adjacent lines
- Junction Validity - T-joins and crosses must have correct incoming/outgoing connections
- Line Continuity - Horizontal lines (─═) should terminate at valid endpoints
- Box Closure - Boxes should be properly closed (no dangling edges)
Exit Codes
| Code | Meaning |
|---|---|
| 0 | No issues found |
| 1 | Errors detected |
| 2 | Warnings only (errors ignored with --warn-only) |
Integration with Claude Code
When Claude Code creates or edits ASCII diagrams:
- Run the validator script on the file
- Review any errors in the output
- Apply suggested fixes
- Re-run until clean
Example Workflow
/usr/bin/env bash << 'PREFLIGHT_EOF_4'
# After editing docs/ARCHITECTURE.md
uv run "$(cc-plugin-root doc-tools)/skills/ascii-diagram-validator/scripts/check_ascii_alignment.py" docs/ARCHITECTURE.md
# If errors found, Claude Code can read the output and fix:
# docs/ARCHITECTURE.md:45:12: error: vertical connector '│' at column 12 has no matching character above
# → Edit line 44, column 12 to add the missing connector
PREFLIGHT_EOF_4
Limitations
- Detects structural alignment issues, not aesthetic spacing
- Requires consistent use of box-drawing characters (no mixed ASCII like +---+)
- Tab characters may cause false positives (convert to spaces first)
- Unicode normalization not performed (use pre-composed characters)
Bundled Scripts
| Script | Purpose |
|---|---|
scripts/check_ascii_alignment.py | Main validation script |
Related
Troubleshooting
| Issue | Cause | Solution |
|---|---|---|
| Script not found | Plugin not installed | Verify plugin installed with claude plugin list |
| False positives with tabs | Tab characters misalign | Convert tabs to spaces before validation |
| Mixed ASCII not detected | Using +---+ style | Script only validates Unicode box-drawing chars |
| Column numbers off | Unicode width calculation | Use pre-composed characters, avoid combining marks |
| No issues but looks wrong | Aesthetic spacing not checked | Validator checks structure, not visual spacing |
| Exit code 2 unexpected | warnings only mode | Use --warn-only flag to treat warnings as success |
| Can't find validation error | Complex nested diagram | Check line numbers in output, validate section only |
| Unicode chars not rendering | Terminal font missing glyphs | Use font with full Unicode box-drawing support |
Post-Execution Reflection
After this skill completes, check before closing:
- Did the command succeed? — If not, fix the instruction or error table that caused the failure.
- Did parameters or output change? — If the underlying tool's interface drifted, update Usage examples and Parameters table to match.
- Was a workaround needed? — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.
Only update if the issue is real and reproducible — not speculative.