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.