document-gen-fallback

Document Generation Fallback Workflow

When to Use

Use this skill when shell_agent returns unknown or unclear errors on complex document generation tasks, especially when:

• Generating documents in multiple formats (e.g., .docx, .pdf, .html)
• The error message doesn't provide clear debugging information
• You need better visibility into each step of the generation process

Core Technique

Instead of delegating the entire document generation to shell_agent, manually split the workflow into discrete, observable steps:

1. Content creation → Use write_file to create source document (Markdown)
2. Format conversion → Use run_shell with pandoc for each target format
3. Verification → Check output files exist and are valid

Step-by-Step Workflow

Step 1: Create Source Content with write_file

Write your document content as Markdown to a temporary source file. This gives you full visibility into the content being generated.

write_file
path: /tmp/document_source.md
content: |
  # Document Title
  
  ## Section 1
  Content here...
  
  ## Section 2
  More content...

Step 2: Convert to Target Formats with run_shell

Use run_shell with explicit pandoc commands for each format. This isolates conversion errors.

run_shell
command: pandoc /tmp/document_source.md -o output.docx

run_shell
command: pandoc /tmp/document_source.md -o output.pdf

Step 3: Verify Outputs

Check that files were created successfully:

run_shell
command: ls -lh output.docx output.pdf

Complete Example

# Generate Negotiation Strategy Document

## Step 1: Write Markdown source
write_file
path: /tmp/negotiation_strategy.md
content: |
  # Negotiation Strategy
  
  ## Executive Summary
  [Content...]
  
  ## Resolution Path
  [Content...]
  
  ## BATNA Analysis
  [Content...]

## Step 2: Convert to DOCX
run_shell
command: pandoc /tmp/negotiation_strategy.md -o negotiation_strategy.docx

## Step 3: Convert to PDF
run_shell
command: pandoc /tmp/negotiation_strategy.md -o negotiation_strategy.pdf

## Step 4: Verify
run_shell
command: ls -lh negotiation_strategy.*

Advantages Over shell_agent

| Aspect | shell_agent | Manual Workflow | |--------|-------------|-----------------| | Error visibility | Opaque, may retry silently | Each step shows explicit output | | Recovery | Automatic but may loop | Manual intervention at specific step | | Debugging | Hard to isolate failure point | Clear which step failed | | Control | Agent decides approach | You control each conversion |

Common pandoc Commands

# Markdown to Word
pandoc input.md -o output.docx

# Markdown to PDF (requires LaTeX or wkhtmltopdf)
pandoc input.md -o output.pdf

# Markdown to HTML
pandoc input.md -o output.html

# With custom template
pandoc input.md --template=template.html -o output.html

# With metadata
pandoc input.md -o output.pdf --metadata title="Document Title"

Troubleshooting

• PDF generation fails: Ensure LaTeX is installed (texlive package) or use --pdf-engine=wkhtmltopdf
• DOCX formatting issues: Add --reference-doc=template.docx for custom styles
• Unicode/encoding errors: Add -f markdown+utf8 to pandoc command
• Missing pandoc: Install via apt-get install pandoc or brew install pandoc

When to Return to shell_agent

After successfully completing the manual workflow once, you can attempt shell_agent again for similar tasks, now with a known-working fallback if errors recur.