document-gen-resilient-workflow

Resilient Document Generation Workflow

When to Use

Use this skill when document generation tasks encounter tool errors or failures, especially:

• run_shell commands return 'unknown error' without diagnostic details
• PDF generation fails with LaTeX encoding or missing engine errors
• You need fallback options when primary conversion methods fail
• Workspace or path issues cause file access problems
• Unicode/special characters cause rendering issues in PDF output
• shell_agent has failed multiple times on similar tasks

Core Technique

Split document generation into observable, verifiable steps with explicit error capture and progressive fallback:

1. Validate workspace → Confirm current directory and write permissions
2. Pre-flight checks → Verify required tools (pandoc, LaTeX engines) are available
3. Content creation → Use write_file for source Markdown with full visibility
4. Unicode sanitization → Preprocess for PDF conversion when needed
5. Progressive conversion → Try multiple engines/methods until one succeeds
6. Explicit error capture → Redirect stderr to diagnose failures
7. Verification → Confirm output files exist and are readable

⚠️ Critical: Tool Error Patterns

'unknown error' from run_shell: This typically indicates:

• Sandbox execution context issues (not the command itself)
• Missing stderr capture preventing diagnosis
• Transient file access problems

Solution: Use explicit error capture with 2>&1 and verify tool availability first:

run_shell
command: pandoc --version 2>&1 || echo "PANDOC NOT AVAILABLE"

Pre-Flight Checklist

Before starting conversion, verify your environment:

## Pre-Flight Checks

### Check 1: Verify working directory
run_shell
command: pwd && ls -la

### Check 2: Verify pandoc availability
run_shell
command: pandoc --version 2>&1 | head -3 || echo "PANDOC MISSING"

### Check 3: Check LaTeX engines
run_shell
command: which pdflatex xelatex wkhtmltopdf 2>&1 || echo "Some engines missing"

### Check 4: Check Python libraries (fallback option)
run_shell
command: python3 -c "import fpdf; print('fpdf OK')" 2>&1 || echo "fpdf missing"
run_shell
command: python3 -c "import docx; print('python-docx OK')" 2>&1 || echo "python-docx missing"