Document Generation with Diagnostic Workflow (Unicode-Safe)

When to Use

Use this skill when document generation tasks fail or return unclear errors, especially when:

• Generating documents in multiple formats (.docx, .pdf, .html)
• PDF generation fails with encoding/LaTeX errors
• shell_agent returns "unknown error" without diagnostics
• Documents contain special characters, symbols, or non-ASCII text
• You need systematic error diagnosis rather than blind retries

⚠️ Critical: Why This Skill Exists

Recent executions show 43% effectiveness because agents:

• Skip unicode sanitization before PDF conversion
• Don't try xelatex engine (better Unicode support)
• Don't capture stderr for proper diagnosis
• Exhaust iterations on repeated failures without systematic troubleshooting

This skill fixes those gaps with mandatory steps.

Pre-Flight Validation (NEW - Required Step 0)

Before starting document generation, verify your toolchain:

run_shell
command: which pandoc && pandoc --version | head -3

run_shell
command: which pdflatex xelatex wkhtmltopdf 2>/dev/null || echo "Some engines missing"

run_shell
command: python3 -c "import sys; print(sys.version)"

If pandoc is missing, install it:

run_shell
command: apt-get update && apt-get install -y pandoc

For PDF support, install LaTeX engines:

run_shell
command: apt-get install -y texlive-latex-recommended texlive-fonts-recommended texlive-xetex

Core Technique

Manually split the workflow into observable, diagnostic steps:

1. Pre-flight → Verify toolchain availability
2. Content creation → Use write_file for markdown source (visible content)
3. Unicode sanitization → MANDATORY for PDF: Create sanitized version
4. Format conversion with fallback → Try engines in order, capture stderr
5. Verification → Check outputs exist and validate content

Unicode & LaTeX Compatibility (MANDATORY for PDF)