[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6KFDDDP74G9ZHJWZ10TCJS4":3,"skill-same:01M6KFDDDP74G9ZHJWZ10TCJS4":80},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":26,"publishedAt":41,"linkOnly":42,"markdownContent":43,"markdownBody":44,"frontMatter":45,"refName":46,"commitSha":47,"skillDirectory":48,"forksCount":14,"repositoryHtmlUrl":49,"repositoryHomepageUrl":6,"ownerHtmlUrl":50,"ownerBlogUrl":51,"ownerDescription":52,"updatedAt":53,"install":54,"resources":67},"01M6KFDDDP74G9ZHJWZ10TCJS4","document-gen-resilient-workflow",null,"Robust document generation with engine fallback chain, error diagnostics, and Python alternatives","xyliu-cs\u002FOpenSpace-GDPval","xyliu-cs","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F89236536?v=4","01M6KF8Z1V4TXS86CKSH48BY8T","xy","01M6KF8Z67443W0SHXM85JEF0B",0,"MIT","https:\u002F\u002Fgithub.com\u002Fxyliu-cs\u002FOpenSpace-GDPval\u002Fblob\u002Fmain\u002Fgdpval_bench\u002Fskills\u002Fdocument-gen-fallback-enhanced-enhanced\u002FSKILL.md",[18,23],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000002","文档处理","SCENARIO","使用场景",{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发",[27,28,29,30,31,32,33,34,35,36,37,38,39,40],"workflow","document","document gen resilient workflow","document gen resilient","python","diagnostics","engine","fallback","generation","chain","error","document generation","with","alternatives","2026-11-10 10:12:30",false,"---\nname: document-gen-resilient-workflow\ndescription: Robust document generation with engine fallback chain, error diagnostics, and Python alternatives\n---\n\n# Resilient Document Generation Workflow\n\n## When to Use\n\nUse this skill when document generation tasks encounter tool errors or failures, especially:\n- `run_shell` commands return 'unknown error' without diagnostic details\n- PDF generation fails with LaTeX encoding or missing engine errors\n- You need fallback options when primary conversion methods fail\n- **Workspace or path issues** cause file access problems\n- Unicode\u002Fspecial characters cause rendering issues in PDF output\n- `shell_agent` has failed multiple times on similar tasks\n\n## Core Technique\n\nSplit document generation into **observable, verifiable steps** with explicit error capture and progressive fallback:\n\n1. **Validate workspace** → Confirm current directory and write permissions\n2. **Pre-flight checks** → Verify required tools (pandoc, LaTeX engines) are available\n3. **Content creation** → Use `write_file` for source Markdown with full visibility\n4. **Unicode sanitization** → Preprocess for PDF conversion when needed\n5. **Progressive conversion** → Try multiple engines\u002Fmethods until one succeeds\n6. **Explicit error capture** → Redirect stderr to diagnose failures\n7. **Verification** → Confirm output files exist and are readable\n\n## ⚠️ Critical: Tool Error Patterns\n\n**'unknown error' from run_shell**: This typically indicates:\n- Sandbox execution context issues (not the command itself)\n- Missing stderr capture preventing diagnosis\n- Transient file access problems\n\n**Solution**: Use explicit error capture with `2>&1` and verify tool availability first:\n```\nrun_shell\ncommand: pandoc --version 2>&1 || echo \"PANDOC NOT AVAILABLE\"\n```\n\n## Pre-Flight Checklist\n\nBefore starting conversion, verify your environment:\n\n```markdown\n## Pre-Flight Checks\n\n### Check 1: Verify working directory\nrun_shell\ncommand: pwd && ls -la\n\n### Check 2: Verify pandoc availability\nrun_shell\ncommand: pandoc --version 2>&1 | head -3 || echo \"PANDOC MISSING\"\n\n### Check 3: Check LaTeX engines\nrun_shell\ncommand: which pdflatex xelatex wkhtmltopdf 2>&1 || echo \"Some engines missing\"\n\n### Check 4: Check Python libraries (fallback option)\nrun_shell\ncommand: python3 -c \"import fpdf; print('fpdf OK')\" 2>&1 || echo \"fpdf missing\"\nrun_shell\ncommand: python3 -c \"import docx; print('python-docx OK')\" 2>&1 || echo \"python-docx missing\"\n```\n\n## Complete Step-by-Step Workflow\n\n### Step 1: Validate Workspace\n\nConfirm you're in the correct directory and can write files:\n\n```\nrun_shell\ncommand: pwd && echo \"Test write\" > \u002Ftmp\u002Fworkspace_test_$$.txt && ls -la \u002Ftmp\u002Fworkspace_test_$$.txt && rm \u002Ftmp\u002Fworkspace_test_$$.txt\n```\n\n**If this fails**, you may have directory permission issues. Use absolute paths for all files.\n\n### Step 2: Create Source Content with write_file\n\nWrite document content as Markdown to a source file:\n\n```\nwrite_file\npath: \u002Ftmp\u002Fdocument_source.md\ncontent: |\n  # Document Title\n  \n  ## Section 1\n  Content here...\n```\n\n### Step 3: Unicode Sanitization (PDF Only)\n\n**Only needed for PDF conversion via LaTeX engines**. DOCX and HTML handle Unicode natively.\n\nCreate a sanitized version replacing LaTeX-problematic characters:\n\n```\nwrite_file\npath: \u002Ftmp\u002Fdocument_source_sanitized.md\ncontent: |\n  # Document Title\n  \n  [Same content with: em-dash → --, curly quotes → straight, → arrows → text, etc.]\n```\n\n**Common replacements** (see full table below):\n| Original | Replace With |\n|----------|--------------|\n| `—` (em dash) | `--` |\n| `\" \"` (curly quotes) | `\" \"` (straight) |\n| `…` (ellipsis) | `...` |\n| `→` `←` (arrows) | `->` `\u003C-` |\n| `✓` `✗` | `[x]` `[ ]` |\n| `©` `®` `™` | `(c)` `(r)` `(tm)` |\n\n**Alternative**: Use sanitization script (see Scripts section below).\n\n### Step 4: Progressive Format Conversion\n\nTry multiple methods in order of preference. **Capture stderr explicitly** for diagnosis.\n\n#### Method A: DOCX Conversion (Most Reliable)\n\n```\nrun_shell\ncommand: pandoc \u002Ftmp\u002Fdocument_source.md -o output.docx 2>&1 && echo \"SUCCESS\" || echo \"FAILED: $?\"\n```\n\nIf this fails, try with explicit UTF-8 flag:\n```\nrun_shell\ncommand: pandoc \u002Ftmp\u002Fdocument_source.md -f markdown+utf8 -o output.docx 2>&1\n```\n\n#### Method B: PDF Conversion (Progressive Fallback)\n\n**Try engines in this order** until one succeeds:\n\n```\nrun_shell\ncommand: pandoc \u002Ftmp\u002Fdocument_source_sanitized.md -o output.pdf 2>&1 | tee \u002Ftmp\u002Fpdf_error.log && echo \"PDF SUCCESS\"\n```\n\nIf Method B fails, check error log and try next engine:\n\n```\nrun_shell\ncommand: pandoc \u002Ftmp\u002Fdocument_source_sanitized.md --pdf-engine=xelatex -o output.pdf 2>&1 | tee \u002Ftmp\u002Fpdf_error.log && echo \"PDF SUCCESS\"\n```\n\nIf xelatex fails:\n```\nrun_shell\ncommand: pandoc \u002Ftmp\u002Fdocument_source_sanitized.md --pdf-engine=wkhtmltopdf -o output.pdf 2>&1 | tee \u002Ftmp\u002Fpdf_error.log && echo \"PDF SUCCESS\"\n```\n\n#### Method C: Python Library Fallback (When pandoc Unavailable)\n\nIf all pandoc methods fail, use Python libraries:\n\n**Option C1: FPDF2 for PDF**\n```\nexecute_code_sandbox\nlanguage: python\ncode: |\n  from fpdf import FPDF\n  \n  pdf = FPDF()\n  pdf.add_page()\n  pdf.set_font('Arial', 'B', 16)\n  pdf.cell(40, 10, 'Document Title')\n  pdf.ln(20)\n  pdf.set_font('Arial', '', 12)\n  pdf.multi_cell(0, 10, 'Your content here...')\n  pdf.output('output.pdf')\n  print('PDF created successfully')\n```\n\n**Option C2: python-docx for DOCX**\n```\nexecute_code_sandbox\nlanguage: python\ncode: |\n  from docx import Document\n  \n  doc = Document()\n  doc.add_heading('Document Title', 0)\n  doc.add_paragraph('Your content here...')\n  doc.save('output.docx')\n  print('DOCX created successfully')\n```\n\n### Step 5: Verify Output Files\n\nDon't just check existence—verify files are valid:\n\n```\nrun_shell\ncommand: ls -lh output.* 2>&1\n```\n\n```\nrun_shell\ncommand: file output.docx output.pdf 2>&1\n```\n\nFor DOCX, verify content:\n```\nrun_shell\ncommand: unzip -p output.docx word\u002Fdocument.xml 2>&1 | head -50 || echo \"Cannot read DOCX\"\n```\n\nFor PDF, check page count:\n```\nrun_shell\ncommand: pdfinfo output.pdf 2>&1 | grep Pages || echo \"pdfinfo not available\"\n```\n\nAlternative verification via Python:\n```\nexecute_code_sandbox\ncode: |\n  import os\n  for f in ['output.docx', 'output.pdf', 'output.html']:\n    if os.path.exists(f):\n      size = os.path.getsize(f)\n      print(f'{f}: {size} bytes')\n    else:\n      print(f'{f}: NOT FOUND')\n```\n\n## Complete Example: Generating a Report\n\n```markdown\n# Generate Quarterly Report (DOCX + PDF)\n\n## Step 1: Pre-flight checks\nrun_shell\ncommand: pandoc --version 2>&1 | head -1\n\n## Step 2: Write Markdown source\nwrite_file\npath: \u002Ftmp\u002Fquarterly_report.md\ncontent: |\n  # Quarterly Business Report\n  \n  ## Executive Summary\n  Q4 performance exceeded expectations...\n  \n  ## Key Metrics\n  - Revenue: $1.2M\n  - Growth: 15%\n  \n  ## Recommendations\n  Continue current strategy...\n\n## Step 3: Create sanitized version for PDF\nwrite_file\npath: \u002Ftmp\u002Fquarterly_report_sanitized.md\ncontent: |\n  # Quarterly Business Report\n  \n  ## Executive Summary\n  Q4 performance exceeded expectations...\n  \n  [Rest of content with special chars replaced]\n\n## Step 4: Generate DOCX\nrun_shell\ncommand: pandoc \u002Ftmp\u002Fquarterly_report.md -o quarterly_report.docx 2>&1 && echo \"DOCX OK\"\n\n## Step 5: Generate PDF (try xelatex for Unicode safety)\nrun_shell\ncommand: pandoc \u002Ftmp\u002Fquarterly_report_sanitized.md --pdf-engine=xelatex -o quarterly_report.pdf 2>&1 && echo \"PDF OK\"\n\n## Step 6: Verify outputs\nrun_shell\ncommand: ls -lh quarterly_report.* && file quarterly_report.*\n```\n\n## Full Unicode Replacement Table\n\n| Character | Unicode | Issue | Safe Replacement |\n|-----------|---------|-------|------------------|\n| `—` | U+2014 | LaTeX incompatible | `--` |\n| `–` | U+2013 | LaTeX incompatible | `-` |\n| `\"` `\"` | U+201C\u002FU+201D | Encoding errors | `\"` (straight) |\n| `'` `'` | U+2018\u002FU+2019 | Encoding errors | `'` (straight) |\n| `…` | U+2026 | May not render | `...` |\n| `→` | U+2192 | LaTeX incompatible | `->` or `to` |\n| `←` | U+2190 | LaTeX incompatible | `\u003C-` |\n| `↑` `↓` | U+2191\u002FU+2193 | LaTeX incompatible | `^` `v` |\n| `•` | U+2022 | Font-dependent | `-` or `*` |\n| `✓` | U+2713 | May not render | `[x]` |\n| `✗` | U+2717 | May not render | `[ ]` |\n| `★` `●` | U+2605\u002FU+25CF | May not render | `*` `-` |\n| `©` | U+00A9 | May require packages | `(c)` |\n| `®` | U+00AE | May require packages | `(r)` |\n| `™` | U+2122 | May require packages | `(tm)` |\n| `é` `ñ` `ü` | Various | Font-dependent | Use xelatex or replace |\n\n## Reusable Sanitization Script\n\nSave this script for repeated use:\n\n```bash\n#!\u002Fbin\u002Fbash\n# sanitize_for_pdf.sh - Replace problematic unicode chars for LaTeX\u002FPDF\nset -e\nif [ -z \"$1\" ]; then\n  echo \"Usage: $0 \u003Cinput.md> [output.md]\"\n  exit 1\nfi\nINPUT=\"$1\"\nOUTPUT=\"${2:-${1%.md}_sanitized.md}\"\n\nsed -e 's\u002F—\u002F--\u002Fg' \\\n    -e 's\u002F–\u002F-\u002Fg' \\\n    -e 's\u002F\"\\([^\"]*\\)\"\u002F\"\\1\"\u002Fg' \\\n    -e \"s\u002F'\\([^']*\\)'\u002F\\'\\1\\'\u002Fg\" \\\n    -e 's\u002F…\u002F...\u002Fg' \\\n    -e 's\u002F→\u002F->\u002Fg' \\\n    -e 's\u002F←\u002F\u003C-\u002Fg' \\\n    -e 's\u002F↑\u002F^\u002Fg' \\\n    -e 's\u002F↓\u002Fv\u002Fg' \\\n    -e 's\u002F•\u002F-\u002Fg' \\\n    -e 's\u002F✓\u002F[x]\u002Fg' \\\n    -e 's\u002F✗\u002F[ ]\u002Fg' \\\n    -e 's\u002F★\u002F*\u002Fg' \\\n    -e 's\u002F©\u002F(c)\u002Fg' \\\n    -e 's\u002F®\u002F(r)\u002Fg' \\\n    -e 's\u002F™\u002F(tm)\u002Fg' \\\n    \"$INPUT\" > \"$OUTPUT\"\n\necho \"Sanitized: $INPUT -> $OUTPUT\"\n```\n\nUsage:\n```\nrun_shell\ncommand: chmod +x sanitize_for_pdf.sh && .\u002Fsanitize_for_pdf.sh \u002Ftmp\u002Fdocument_source.md \u002Ftmp\u002Fdocument_source_sanitized.md\n```\n\n## Error Diagnosis Guide\n\n### Error: \"unknown error\" from run_shell\n\n**Diagnosis:**\n```\nrun_shell\ncommand: pandoc --version 2>&1\nrun_shell\ncommand: echo \"test\" | pandoc -f markdown -t plain 2>&1\n```\n\n**If pandoc works in isolation**, the issue is likely:\n- File path problems (use absolute paths)\n- Sandbox context issues (retry or use shell_agent)\n- Transient errors (retry the same command)\n\n### Error: \"LaTeX not found\" or \"pdflatex: command not found\"\n\n**Solutions in order:**\n1. Try xelatex: `--pdf-engine=xelatex`\n2. Try wkhtmltopdf: `--pdf-engine=wkhtmltopdf`\n3. Install LaTeX: `apt-get install texlive-latex-recommended texlive-fonts-recommended`\n4. Use Python fpdf2 fallback (see Step 4, Method C)\n\n### Error: \"Encoding error\" or \"Invalid UTF-8\"\n\n**Solutions:**\n1. Add UTF-8 flag: `pandoc -f markdown+utf8`\n2. Check file encoding: `file -i source.md`\n3. Re-save with explicit UTF-8: \n   ```\n   run_shell\n   command: iconv -f UTF-8 -t UTF-8 source.md -o source_utf8.md\n   ```\n4. Use sanitization step\n\n### Error: PDF generated but empty or garbled\n\n**Diagnosis:**\n```\nrun_shell\ncommand: pdfinfo output.pdf 2>&1\n```\n```\nexecute_code_sandbox\ncode: |\n  import fitz  # PyMuPDF\n  doc = fitz.open('output.pdf')\n  print(f'Pages: {doc.page_count}')\n  if doc.page_count > 0:\n      page = doc[0]\n      print(f'Text: {page.get_text()[:200]}')\n```\n\n**Solutions:**\n1. Use xelatex engine with Unicode content\n2. Check sanitization step (if using pdflatex)\n3. Verify source markdown is valid\n\n### Error: DOCX file won't open or shows error\n\n**Diagnosis:**\n```\nrun_shell\ncommand: unzip -l output.docx 2>&1 | head -10\n```\n\n**Solutions:**\n1. Add `--reference-doc` with valid template\n2. Ensure markdown syntax is valid\n3. Try pandoc verbose mode: `pandoc -v input.md -o output.docx 2>&1`\n\n## Workspace Troubleshooting\n\n### Files appearing in wrong directory\n\n**Diagnosis:**\n```\nrun_shell\ncommand: pwd && find \u002Ftmp -name \"*.docx\" -o -name \"*.pdf\" 2>\u002Fdev\u002Fnull | head -10\n```\n\n**Solutions:**\n1. Use absolute paths in all commands\n2. Explicitly change to target directory: `cd \u002Fpath\u002Fto\u002Fworkspace && ...`\n3. After generation, copy files to correct location:\n   ```\n   run_shell\n   command: cp \u002Ftmp\u002Foutput.docx .\u002Foutput.docx\n   ```\n\n### Permission denied errors\n\n**Solutions:**\n1. Use \u002Ftmp directory for intermediate files\n2. Copy final output to target location\n3. Check disk space: `df -h .`\n\n## When to Use shell_agent vs Manual Workflow\n\n| Situation | Recommended Approach |\n|-----------|---------------------|\n| Simple DOCX generation, no special chars | `shell_agent` (faster) |\n| PDF with Unicode\u002Fsymbols | Manual workflow with sanitization |\n| Multiple 'unknown error' failures | Manual workflow with error capture |\n| Need to debug conversion issues | Manual workflow (visible steps) |\n| Time-critical, simple format | `shell_agent` |\n| Critical document, must succeed | Manual workflow with fallbacks |\n\n## Alternative: Hybrid Approach\n\nFor reliability with less manual effort:\n\n```markdown\n## Hybrid Workflow\n\n1. **First attempt**: `shell_agent` with clear task description\n\n2. **On first error**: Switch to manual workflow:\n   - `write_file` for source\n   - `run_shell` with error capture (2>&1)\n   - Verify with explicit checks\n\n3. **On repeated errors**: Use Python library fallback (execute_code_sandbox)\n\nThis balances speed with reliability.\n```\n\n## Related Skills\n\n- `workspace-path-troubleshooting`: For diagnosing file location issues\n- `pdf-verification-cli`: For validating generated PDFs\n- `write-file-fallback-report`: For content-first document creation when web sources fail\n\n## Quick Reference Card\n\n```\nQUICK START: Generate Document in 3 Formats\n\n1. Write source: write_file → \u002Ftmp\u002Fdoc.md\n\n2. Sanitize (PDF only): \n   Replace: — → --, \"\" → \"\", … → ...\n\n3. Convert with error capture:\n   DOCX: pandoc \u002Ftmp\u002Fdoc.md -o out.docx 2>&1\n   PDF:  pandoc \u002Ftmp\u002Fdoc_sanitized.md --pdf-engine=xelatex -o out.pdf 2>&1\n   HTML: pandoc \u002Ftmp\u002Fdoc.md -o out.html 2>&1\n\n4. Verify: ls -lh out.* && file out.*\n\n5. If pandoc fails: Use execute_code_sandbox with fpdf2 or python-docx\n```\n","# Resilient Document Generation Workflow\n\n## When to Use\n\nUse this skill when document generation tasks encounter tool errors or failures, especially:\n- `run_shell` commands return 'unknown error' without diagnostic details\n- PDF generation fails with LaTeX encoding or missing engine errors\n- You need fallback options when primary conversion methods fail\n- **Workspace or path issues** cause file access problems\n- Unicode\u002Fspecial characters cause rendering issues in PDF output\n- `shell_agent` has failed multiple times on similar tasks\n\n## Core Technique\n\nSplit document generation into **observable, verifiable steps** with explicit error capture and progressive fallback:\n\n1. **Validate workspace** → Confirm current directory and write permissions\n2. **Pre-flight checks** → Verify required tools (pandoc, LaTeX engines) are available\n3. **Content creation** → Use `write_file` for source Markdown with full visibility\n4. **Unicode sanitization** → Preprocess for PDF conversion when needed\n5. **Progressive conversion** → Try multiple engines\u002Fmethods until one succeeds\n6. **Explicit error capture** → Redirect stderr to diagnose failures\n7. **Verification** → Confirm output files exist and are readable\n\n## ⚠️ Critical: Tool Error Patterns\n\n**'unknown error' from run_shell**: This typically indicates:\n- Sandbox execution context issues (not the command itself)\n- Missing stderr capture preventing diagnosis\n- Transient file access problems\n\n**Solution**: Use explicit error capture with `2>&1` and verify tool availability first:\n```\nrun_shell\ncommand: pandoc --version 2>&1 || echo \"PANDOC NOT AVAILABLE\"\n```\n\n## Pre-Flight Checklist\n\nBefore starting conversion, verify your environment:\n\n```markdown\n## Pre-Flight Checks\n\n### Check 1: Verify working directory\nrun_shell\ncommand: pwd && ls -la\n\n### Check 2: Verify pandoc availability\nrun_shell\ncommand: pandoc --version 2>&1 | head -3 || echo \"PANDOC MISSING\"\n\n### Check 3: Check LaTeX engines\nrun_shell\ncommand: which pdflatex xelatex wkhtmltopdf 2>&1 || echo \"Some engines missing\"\n\n### Check 4: Check Python libraries (fallback option)\nrun_shell\ncommand: python3 -c \"import fpdf; print('fpdf OK')\" 2>&1 || echo \"fpdf missing\"\nrun_shell\ncommand: python3 -c \"import docx; print('python-docx OK')\" 2>&1 || echo \"python-docx missing\"\n```\n\n## Complete Step-by-Step Workflow\n\n### Step 1: Validate Workspace\n\nConfirm you're in the correct directory and can write files:\n\n```\nrun_shell\ncommand: pwd && echo \"Test write\" > \u002Ftmp\u002Fworkspace_test_$$.txt && ls -la \u002Ftmp\u002Fworkspace_test_$$.txt && rm \u002Ftmp\u002Fworkspace_test_$$.txt\n```\n\n**If this fails**, you may have directory permission issues. Use absolute paths for all files.\n\n### Step 2: Create Source Content with write_file\n\nWrite document content as Markdown to a source file:\n\n```\nwrite_file\npath: \u002Ftmp\u002Fdocument_source.md\ncontent: |\n  # Document Title\n  \n  ## Section 1\n  Content here...\n```\n\n### Step 3: Unicode Sanitization (PDF Only)\n\n**Only needed for PDF conversion via LaTeX engines**. DOCX and HTML handle Unicode natively.\n\nCreate a sanitized version replacing LaTeX-problematic characters:\n\n```\nwrite_file\npath: \u002Ftmp\u002Fdocument_source_sanitized.md\ncontent: |\n  # Document Title\n  \n  [Same content with: em-dash → --, curly quotes → straight, → arrows → text, etc.]\n```\n\n**Common replacements** (see full table below):\n| Original | Replace With |\n|----------|--------------|\n| `—` (em dash) | `--` |\n| `\" \"` (curly quotes) | `\" \"` (straight) |\n| `…` (ellipsis) | `...` |\n| `→` `←` (arrows) | `->` `\u003C-` |\n| `✓` `✗` | `[x]` `[ ]` |\n| `©` `®` `™` | `(c)` `(r)` `(tm)` |\n\n**Alternative**: Use sanitization script (see Scripts section below).\n\n### Step 4: Progressive Format Conversion\n\nTry multiple methods in order of preference. **Capture stderr explicitly** for diagnosis.\n\n#### Method A: DOCX Conversion (Most Reliable)\n\n```\nrun_shell\ncommand: pandoc \u002Ftmp\u002Fdocument_source.md -o output.docx 2>&1 && echo \"SUCCESS\" || echo \"FAILED: $?\"\n```\n\nIf this fails, try with explicit UTF-8 flag:\n```\nrun_shell\ncommand: pandoc \u002Ftmp\u002Fdocument_source.md -f markdown+utf8 -o output.docx 2>&1\n```\n\n#### Method B: PDF Conversion (Progressive Fallback)\n\n**Try engines in this order** until one succeeds:\n\n```\nrun_shell\ncommand: pandoc \u002Ftmp\u002Fdocument_source_sanitized.md -o output.pdf 2>&1 | tee \u002Ftmp\u002Fpdf_error.log && echo \"PDF SUCCESS\"\n```\n\nIf Method B fails, check error log and try next engine:\n\n```\nrun_shell\ncommand: pandoc \u002Ftmp\u002Fdocument_source_sanitized.md --pdf-engine=xelatex -o output.pdf 2>&1 | tee \u002Ftmp\u002Fpdf_error.log && echo \"PDF SUCCESS\"\n```\n\nIf xelatex fails:\n```\nrun_shell\ncommand: pandoc \u002Ftmp\u002Fdocument_source_sanitized.md --pdf-engine=wkhtmltopdf -o output.pdf 2>&1 | tee \u002Ftmp\u002Fpdf_error.log && echo \"PDF SUCCESS\"\n```\n\n#### Method C: Python Library Fallback (When pandoc Unavailable)\n\nIf all pandoc methods fail, use Python libraries:\n\n**Option C1: FPDF2 for PDF**\n```\nexecute_code_sandbox\nlanguage: python\ncode: |\n  from fpdf import FPDF\n  \n  pdf = FPDF()\n  pdf.add_page()\n  pdf.set_font('Arial', 'B', 16)\n  pdf.cell(40, 10, 'Document Title')\n  pdf.ln(20)\n  pdf.set_font('Arial', '', 12)\n  pdf.multi_cell(0, 10, 'Your content here...')\n  pdf.output('output.pdf')\n  print('PDF created successfully')\n```\n\n**Option C2: python-docx for DOCX**\n```\nexecute_code_sandbox\nlanguage: python\ncode: |\n  from docx import Document\n  \n  doc = Document()\n  doc.add_heading('Document Title', 0)\n  doc.add_paragraph('Your content here...')\n  doc.save('output.docx')\n  print('DOCX created successfully')\n```\n\n### Step 5: Verify Output Files\n\nDon't just check existence—verify files are valid:\n\n```\nrun_shell\ncommand: ls -lh output.* 2>&1\n```\n\n```\nrun_shell\ncommand: file output.docx output.pdf 2>&1\n```\n\nFor DOCX, verify content:\n```\nrun_shell\ncommand: unzip -p output.docx word\u002Fdocument.xml 2>&1 | head -50 || echo \"Cannot read DOCX\"\n```\n\nFor PDF, check page count:\n```\nrun_shell\ncommand: pdfinfo output.pdf 2>&1 | grep Pages || echo \"pdfinfo not available\"\n```\n\nAlternative verification via Python:\n```\nexecute_code_sandbox\ncode: |\n  import os\n  for f in ['output.docx', 'output.pdf', 'output.html']:\n    if os.path.exists(f):\n      size = os.path.getsize(f)\n      print(f'{f}: {size} bytes')\n    else:\n      print(f'{f}: NOT FOUND')\n```\n\n## Complete Example: Generating a Report\n\n```markdown\n# Generate Quarterly Report (DOCX + PDF)\n\n## Step 1: Pre-flight checks\nrun_shell\ncommand: pandoc --version 2>&1 | head -1\n\n## Step 2: Write Markdown source\nwrite_file\npath: \u002Ftmp\u002Fquarterly_report.md\ncontent: |\n  # Quarterly Business Report\n  \n  ## Executive Summary\n  Q4 performance exceeded expectations...\n  \n  ## Key Metrics\n  - Revenue: $1.2M\n  - Growth: 15%\n  \n  ## Recommendations\n  Continue current strategy...\n\n## Step 3: Create sanitized version for PDF\nwrite_file\npath: \u002Ftmp\u002Fquarterly_report_sanitized.md\ncontent: |\n  # Quarterly Business Report\n  \n  ## Executive Summary\n  Q4 performance exceeded expectations...\n  \n  [Rest of content with special chars replaced]\n\n## Step 4: Generate DOCX\nrun_shell\ncommand: pandoc \u002Ftmp\u002Fquarterly_report.md -o quarterly_report.docx 2>&1 && echo \"DOCX OK\"\n\n## Step 5: Generate PDF (try xelatex for Unicode safety)\nrun_shell\ncommand: pandoc \u002Ftmp\u002Fquarterly_report_sanitized.md --pdf-engine=xelatex -o quarterly_report.pdf 2>&1 && echo \"PDF OK\"\n\n## Step 6: Verify outputs\nrun_shell\ncommand: ls -lh quarterly_report.* && file quarterly_report.*\n```\n\n## Full Unicode Replacement Table\n\n| Character | Unicode | Issue | Safe Replacement |\n|-----------|---------|-------|------------------|\n| `—` | U+2014 | LaTeX incompatible | `--` |\n| `–` | U+2013 | LaTeX incompatible | `-` |\n| `\"` `\"` | U+201C\u002FU+201D | Encoding errors | `\"` (straight) |\n| `'` `'` | U+2018\u002FU+2019 | Encoding errors | `'` (straight) |\n| `…` | U+2026 | May not render | `...` |\n| `→` | U+2192 | LaTeX incompatible | `->` or `to` |\n| `←` | U+2190 | LaTeX incompatible | `\u003C-` |\n| `↑` `↓` | U+2191\u002FU+2193 | LaTeX incompatible | `^` `v` |\n| `•` | U+2022 | Font-dependent | `-` or `*` |\n| `✓` | U+2713 | May not render | `[x]` |\n| `✗` | U+2717 | May not render | `[ ]` |\n| `★` `●` | U+2605\u002FU+25CF | May not render | `*` `-` |\n| `©` | U+00A9 | May require packages | `(c)` |\n| `®` | U+00AE | May require packages | `(r)` |\n| `™` | U+2122 | May require packages | `(tm)` |\n| `é` `ñ` `ü` | Various | Font-dependent | Use xelatex or replace |\n\n## Reusable Sanitization Script\n\nSave this script for repeated use:\n\n```bash\n#!\u002Fbin\u002Fbash\n# sanitize_for_pdf.sh - Replace problematic unicode chars for LaTeX\u002FPDF\nset -e\nif [ -z \"$1\" ]; then\n  echo \"Usage: $0 \u003Cinput.md> [output.md]\"\n  exit 1\nfi\nINPUT=\"$1\"\nOUTPUT=\"${2:-${1%.md}_sanitized.md}\"\n\nsed -e 's\u002F—\u002F--\u002Fg' \\\n    -e 's\u002F–\u002F-\u002Fg' \\\n    -e 's\u002F\"\\([^\"]*\\)\"\u002F\"\\1\"\u002Fg' \\\n    -e \"s\u002F'\\([^']*\\)'\u002F\\'\\1\\'\u002Fg\" \\\n    -e 's\u002F…\u002F...\u002Fg' \\\n    -e 's\u002F→\u002F->\u002Fg' \\\n    -e 's\u002F←\u002F\u003C-\u002Fg' \\\n    -e 's\u002F↑\u002F^\u002Fg' \\\n    -e 's\u002F↓\u002Fv\u002Fg' \\\n    -e 's\u002F•\u002F-\u002Fg' \\\n    -e 's\u002F✓\u002F[x]\u002Fg' \\\n    -e 's\u002F✗\u002F[ ]\u002Fg' \\\n    -e 's\u002F★\u002F*\u002Fg' \\\n    -e 's\u002F©\u002F(c)\u002Fg' \\\n    -e 's\u002F®\u002F(r)\u002Fg' \\\n    -e 's\u002F™\u002F(tm)\u002Fg' \\\n    \"$INPUT\" > \"$OUTPUT\"\n\necho \"Sanitized: $INPUT -> $OUTPUT\"\n```\n\nUsage:\n```\nrun_shell\ncommand: chmod +x sanitize_for_pdf.sh && .\u002Fsanitize_for_pdf.sh \u002Ftmp\u002Fdocument_source.md \u002Ftmp\u002Fdocument_source_sanitized.md\n```\n\n## Error Diagnosis Guide\n\n### Error: \"unknown error\" from run_shell\n\n**Diagnosis:**\n```\nrun_shell\ncommand: pandoc --version 2>&1\nrun_shell\ncommand: echo \"test\" | pandoc -f markdown -t plain 2>&1\n```\n\n**If pandoc works in isolation**, the issue is likely:\n- File path problems (use absolute paths)\n- Sandbox context issues (retry or use shell_agent)\n- Transient errors (retry the same command)\n\n### Error: \"LaTeX not found\" or \"pdflatex: command not found\"\n\n**Solutions in order:**\n1. Try xelatex: `--pdf-engine=xelatex`\n2. Try wkhtmltopdf: `--pdf-engine=wkhtmltopdf`\n3. Install LaTeX: `apt-get install texlive-latex-recommended texlive-fonts-recommended`\n4. Use Python fpdf2 fallback (see Step 4, Method C)\n\n### Error: \"Encoding error\" or \"Invalid UTF-8\"\n\n**Solutions:**\n1. Add UTF-8 flag: `pandoc -f markdown+utf8`\n2. Check file encoding: `file -i source.md`\n3. Re-save with explicit UTF-8: \n   ```\n   run_shell\n   command: iconv -f UTF-8 -t UTF-8 source.md -o source_utf8.md\n   ```\n4. Use sanitization step\n\n### Error: PDF generated but empty or garbled\n\n**Diagnosis:**\n```\nrun_shell\ncommand: pdfinfo output.pdf 2>&1\n```\n```\nexecute_code_sandbox\ncode: |\n  import fitz  # PyMuPDF\n  doc = fitz.open('output.pdf')\n  print(f'Pages: {doc.page_count}')\n  if doc.page_count > 0:\n      page = doc[0]\n      print(f'Text: {page.get_text()[:200]}')\n```\n\n**Solutions:**\n1. Use xelatex engine with Unicode content\n2. Check sanitization step (if using pdflatex)\n3. Verify source markdown is valid\n\n### Error: DOCX file won't open or shows error\n\n**Diagnosis:**\n```\nrun_shell\ncommand: unzip -l output.docx 2>&1 | head -10\n```\n\n**Solutions:**\n1. Add `--reference-doc` with valid template\n2. Ensure markdown syntax is valid\n3. Try pandoc verbose mode: `pandoc -v input.md -o output.docx 2>&1`\n\n## Workspace Troubleshooting\n\n### Files appearing in wrong directory\n\n**Diagnosis:**\n```\nrun_shell\ncommand: pwd && find \u002Ftmp -name \"*.docx\" -o -name \"*.pdf\" 2>\u002Fdev\u002Fnull | head -10\n```\n\n**Solutions:**\n1. Use absolute paths in all commands\n2. Explicitly change to target directory: `cd \u002Fpath\u002Fto\u002Fworkspace && ...`\n3. After generation, copy files to correct location:\n   ```\n   run_shell\n   command: cp \u002Ftmp\u002Foutput.docx .\u002Foutput.docx\n   ```\n\n### Permission denied errors\n\n**Solutions:**\n1. Use \u002Ftmp directory for intermediate files\n2. Copy final output to target location\n3. Check disk space: `df -h .`\n\n## When to Use shell_agent vs Manual Workflow\n\n| Situation | Recommended Approach |\n|-----------|---------------------|\n| Simple DOCX generation, no special chars | `shell_agent` (faster) |\n| PDF with Unicode\u002Fsymbols | Manual workflow with sanitization |\n| Multiple 'unknown error' failures | Manual workflow with error capture |\n| Need to debug conversion issues | Manual workflow (visible steps) |\n| Time-critical, simple format | `shell_agent` |\n| Critical document, must succeed | Manual workflow with fallbacks |\n\n## Alternative: Hybrid Approach\n\nFor reliability with less manual effort:\n\n```markdown\n## Hybrid Workflow\n\n1. **First attempt**: `shell_agent` with clear task description\n\n2. **On first error**: Switch to manual workflow:\n   - `write_file` for source\n   - `run_shell` with error capture (2>&1)\n   - Verify with explicit checks\n\n3. **On repeated errors**: Use Python library fallback (execute_code_sandbox)\n\nThis balances speed with reliability.\n```\n\n## Related Skills\n\n- `workspace-path-troubleshooting`: For diagnosing file location issues\n- `pdf-verification-cli`: For validating generated PDFs\n- `write-file-fallback-report`: For content-first document creation when web sources fail\n\n## Quick Reference Card\n\n```\nQUICK START: Generate Document in 3 Formats\n\n1. Write source: write_file → \u002Ftmp\u002Fdoc.md\n\n2. Sanitize (PDF only): \n   Replace: — → --, \"\" → \"\", … → ...\n\n3. Convert with error capture:\n   DOCX: pandoc \u002Ftmp\u002Fdoc.md -o out.docx 2>&1\n   PDF:  pandoc \u002Ftmp\u002Fdoc_sanitized.md --pdf-engine=xelatex -o out.pdf 2>&1\n   HTML: pandoc \u002Ftmp\u002Fdoc.md -o out.html 2>&1\n\n4. Verify: ls -lh out.* && file out.*\n\n5. If pandoc fails: Use execute_code_sandbox with fpdf2 or python-docx\n```\n",{"name":5,"description":7},"main","af1b40a42167d09c30b3a63000aa14ace4c1e229","gdpval_bench\u002Fskills\u002Fdocument-gen-fallback-enhanced-enhanced","https:\u002F\u002Fgithub.com\u002Fxyliu-cs\u002FOpenSpace-GDPval","https:\u002F\u002Fgithub.com\u002Fxyliu-cs","https:\u002F\u002Fxyliu-cs.github.io","PhD Student in CS, CUHK-Shenzhen.","2026-04-06 20:32:15",{"source":8,"skillName":5,"commands":55,"prompt":65,"zipAvailable":66},[56,59,62],{"tool":57,"command":58},"npx","npx skills add xyliu-cs\u002FOpenSpace-GDPval --skill document-gen-resilient-workflow",{"tool":60,"command":61},"bunx","bunx skills add xyliu-cs\u002FOpenSpace-GDPval --skill document-gen-resilient-workflow",{"tool":63,"command":64},"pnpm","pnpm dlx skills add xyliu-cs\u002FOpenSpace-GDPval --skill document-gen-resilient-workflow","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fxyliu-cs\u002FOpenSpace-GDPval\u002Fblob\u002Fmain\u002Fgdpval_bench\u002Fskills\u002Fdocument-gen-fallback-enhanced-enhanced\u002FSKILL.md",true,[68,74],{"path":69,"resourceType":70,"resourceTypeDesc":71,"sizeBytes":72,"sourceHtmlUrl":73},".skill_id","OTHER","其他",53,"https:\u002F\u002Fgithub.com\u002Fxyliu-cs\u002FOpenSpace-GDPval\u002Fblob\u002Fmain\u002Fgdpval_bench\u002Fskills\u002Fdocument-gen-fallback-enhanced-enhanced\u002F.skill_id",{"path":75,"resourceType":76,"resourceTypeDesc":77,"sizeBytes":78,"sourceHtmlUrl":79},"sanitize_for_pdf.sh","SCRIPT","脚本",1285,"https:\u002F\u002Fgithub.com\u002Fxyliu-cs\u002FOpenSpace-GDPval\u002Fblob\u002Fmain\u002Fgdpval_bench\u002Fskills\u002Fdocument-gen-fallback-enhanced-enhanced\u002Fsanitize_for_pdf.sh",[81,94,102,117,142,160],{"skillNo":82,"name":83,"nameZh":6,"description":84,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":85,"categories":86,"keywords":87,"publishedAt":41},"01M6KG8MF1S664SWBDENYRSCK8","zip-export-deliverable","Ensures codebase deliverables are properly exported as ZIP archives through a dedicated finalization step","https:\u002F\u002Fgithub.com\u002Fxyliu-cs\u002FOpenSpace-GDPval\u002Fblob\u002Fmain\u002Fgdpval_bench\u002Fskills\u002Fzip-export-deliverable\u002FSKILL.md",[],[88,89,90,91,92,93],"zip export deliverable","zip","export","deliverables","codebase","as",{"skillNo":95,"name":96,"nameZh":6,"description":97,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":98,"categories":99,"keywords":100,"publishedAt":41},"01M6KG8GAZWHHEK7VNJDW0ME21","zip-deliverable-finalization","Ensure codebase deliverables are properly packaged as ZIP exports in a dedicated final step","https:\u002F\u002Fgithub.com\u002Fxyliu-cs\u002FOpenSpace-GDPval\u002Fblob\u002Fmain\u002Fgdpval_bench\u002Fskills\u002Fzip-deliverable-finalization\u002FSKILL.md",[],[101,89,91,92,93],"zip deliverable finalization",{"skillNo":103,"name":104,"nameZh":6,"description":105,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":106,"categories":107,"keywords":108,"publishedAt":41},"01M6KG8CMQQ1PYMNTSRZ9VS1MD","zero-iteration-failure-analysis","Identify and handle agent failures with 0 iterations as pre-execution system issues","https:\u002F\u002Fgithub.com\u002Fxyliu-cs\u002FOpenSpace-GDPval\u002Fblob\u002Fmain\u002Fgdpval_bench\u002Fskills\u002Fzero-iteration-failure-analysis\u002FSKILL.md",[],[109,110,111,112,113,39,114,115,93,116],"failure analysis","ZeRO","analysis","iteration","zero iteration failure analysis","issues","execution","system",{"skillNo":118,"name":119,"nameZh":6,"description":120,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":121,"categories":122,"keywords":128,"publishedAt":41},"01M6KG86W3PA07FT9W58YHHERM","write-file-fallback-report","Generate professional documents using write_file when primary data sources fail, leveraging embedded domain knowledge instead of external retrieval","https:\u002F\u002Fgithub.com\u002Fxyliu-cs\u002FOpenSpace-GDPval\u002Fblob\u002Fmain\u002Fgdpval_bench\u002Fskills\u002Fwrite-file-fallback-report\u002FSKILL.md",[123],{"categoryNo":124,"categoryName":125,"taxonomyType":126,"taxonomyTypeDesc":127},"01JBSEEDCAT000000000000034","行政与办公人员","PROFESSION","适用职业",[34,129,130,131,132,133,134,135,136,137,138,139,140,141],"write","file","report","write file fallback report","domain","professional","sources","retrieval","generate","embedded","documents","data","knowledge",{"skillNo":143,"name":144,"nameZh":6,"description":145,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":146,"categories":147,"keywords":149,"publishedAt":41},"01M6KG82GAEY3GG77CMGCK1C2T","fallback-doc-with-delegation","Generate professional documents after tool failures using shell_agent for complex formats or write_file for simple text\u002Fmarkdown","https:\u002F\u002Fgithub.com\u002Fxyliu-cs\u002FOpenSpace-GDPval\u002Fblob\u002Fmain\u002Fgdpval_bench\u002Fskills\u002Fwrite-file-fallback-report-enhanced\u002FSKILL.md",[148],{"categoryNo":24,"categoryName":25,"taxonomyType":21,"taxonomyTypeDesc":22},[150,39,34,151,152,153,139,137,130,154,155,156,129,157,134,158,159],"fallback doc with delegation","doc","delegation","shell","markdown","tool","text","simple","formats","for",{"skillNo":161,"name":162,"nameZh":6,"description":163,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":164,"categories":165,"keywords":167,"publishedAt":41},"01M6KG7WT7GX5NYCGEFHW22NV7","context-anchored-fallback-report","Generate documents with write_file when retrieval tools fail, with explicit guardrails against task context drift","https:\u002F\u002Fgithub.com\u002Fxyliu-cs\u002FOpenSpace-GDPval\u002Fblob\u002Fmain\u002Fgdpval_bench\u002Fskills\u002Fwrite-file-fallback-report-enhanced-4bc5c2\u002FSKILL.md",[166],{"categoryNo":124,"categoryName":125,"taxonomyType":126,"taxonomyTypeDesc":127},[34,131,168,169,137,130,170,171,129,172,173,136,39,174,139],"context","context anchored fallback report","Guardrails","Tools","task","drift","context drift"]