table

ASCII Table Alignment Skill

THE PROBLEM

LLMs cannot align markdown tables correctly because:

1. Token-by-token generation - No spatial awareness during output
2. Variable character widths - Even in monospace fonts:
   • CJK characters = 2 cells wide
   • Emoji = variable width
   • Combining characters = 0 width
3. No backtracking - Cannot adjust previous output based on later content

No amount of prompt engineering fixes this. The problem is fundamental to how LLMs generate text.

---

THE SOLUTION

Two-phase approach:

1. Generation Phase (LLM) - Focus on content, not alignment
2. Formatting Phase (Script) - wcwidth-based column alignment

---

MANDATORY PROTOCOL

When generating markdown tables, you MUST follow this protocol:

Step 1: Generate Table Content

Focus on correctness and completeness. Do NOT waste effort on manual alignment.

| Column A | Column B | Column C |
|---|---|---|
| Short | Much longer content here | X |
| Another row | Data | More data |

Step 2: Run Formatter (MANDATORY)

After generating any markdown table, you MUST run:

python3 ~/.claude/scripts/md-table-formatter.py /path/to/file.md

Or for stdin/stdout:

echo "table content" | python3 ~/.claude/scripts/md-table-formatter.py

Step 3: Verify Output

Check stderr for verification report:

TABLE_FORMAT_CHECK:
- Tables processed: N
- Column widths: [W1, W2, W3, ...]
- Status: ALIGNED

---

GENERATION GUIDELINES

When creating table content:

1. Use simple separators - |---|---|---| not |:---:|:---:|:---:|
2. Content first - Get the data right, formatting comes later
3. One table at a time - Easier to verify
4. Preserve semantics - Formatter only adjusts spacing

What the Formatter Does

• Calculates display width of each cell using wcwidth
• Finds maximum width for each column
• Pads cells with spaces to align columns
• Normalizes separator rows