document-gen-unicode-safe

Document Generation Fallback Workflow (Unicode-Safe)

When to Use

First, assess whether to delegate to shell_agent or use manual workflow:

✅ Use shell_agent Directly When:

• Document is straightforward (no special Unicode characters, symbols, or non-ASCII text)
• Single format output needed (e.g., just .docx)
• Content is primarily ASCII text with standard punctuation
• No complex formatting requirements (tables, equations, custom templates)
• You want quick iteration and shell_agent has succeeded on similar tasks before

⚠️ Use Manual Workflow When:

• shell_agent returns unknown or unclear errors
• Document contains special characters, symbols, or non-ASCII text (see Unicode table below)
• Generating multiple formats simultaneously (e.g., .docx, .pdf, .html)
• PDF generation fails due to LaTeX encoding issues
• You need fine-grained control over each conversion step
• Previous shell_agent attempts failed on similar content

📋 Decision Checklist

1. Does the document contain: em-dashes (—), curly quotes (" "), arrows (→), 
   checkmarks (✓), or other special symbols? → Use Manual Workflow

2. Is non-ASCII text present (é, ñ, ü, 中文，العربية)? → Use Manual Workflow with sanitization

3. Did shell_agent already fail on this or similar content? → Use Manual Workflow

4. Need multiple output formats with guaranteed success? → Use Manual Workflow

5. Simple ASCII document, single format, first attempt? → Try shell_agent First

Core Technique

Quick Path (for straightforward documents): Delegate directly to shell_agent with clear instructions:

shell_agent
task: Create a Word document from markdown content. Write the markdown to 
      /tmp/document.md, then convert to .docx using pandoc, and verify the output exists.

Manual Path (for complex/Unicode-heavy documents): Split the workflow into discrete, observable steps:

1. Content creation → Use write_file to create source document (Markdown)
2. Unicode sanitization → Preprocess markdown to replace problematic characters before PDF conversion
3. Format conversion → Use run_shell with pandoc for each target format
4. Verification → Check output files exist and are valid