Debug PDF Skill

Automate the lifecycle of an extraction failure: Failure -> Analysis -> Fixture -> Test

Why This Exists

Extractors (Marker, Surya, Camelot) break on specific PDF patterns (scanned pages, TOC dots, cursed fonts, watermarks). Manually reproducing these bugs is slow.

/debug-pdf

fast-tracks this by:

1. Downloading the failed artifact
2. Identifying structural "traps" (TOC dots, watermarks, ligatures, etc.)
3. Generating minimal reproduction fixtures using

   fixture-tricky

4. Combining multiple failures into a single stress test PDF

Quick Start

# Analyze a single failed URL
./run.sh analyze "https://example.com/broken.pdf"

# Process multiple failures in batch
./run.sh batch failed_urls.txt --output report.json

# Combine all fixtures into one stress test PDF
./run.sh combine stress_test.pdf --max-pages 20

# List known failure patterns
./run.sh list-patterns

# Check session status
./run.sh status

Commands

analyze <url>

Analyze a single PDF URL and optionally generate a reproduction fixture.

./run.sh analyze "https://example.com/broken.pdf"
./run.sh analyze "https://example.com/broken.pdf" --no-repro
./run.sh analyze "https://example.com/broken.pdf" --send-inbox

batch <url-file>

Process multiple URLs from a file (one URL per line).

# Create URL file
echo "https://example.com/doc1.pdf" > failed.txt
echo "https://example.com/doc2.pdf" >> failed.txt

# Run batch analysis
./run.sh batch failed.txt --output analysis.json --send-inbox

combine [output.pdf]

Merge all generated fixtures into a single stress test PDF.

./run.sh combine stress_test.pdf --max-pages 15

list-patterns

Display all known failure patterns and their descriptions.

status

Show current debug session status and fixture count.

Detected Patterns (14/17 = 82%)

Structural (4/4 detected):

• scanned_no_ocr

  - Scanned image PDF without text layer

• sparse_content_slides

  - Slide deck with minimal text per page

• multi_column

  - Complex multi-column layouts (via text block analysis)

• watermarks

  - Text obscured by watermark overlays

Encoding (5/5 detected):

• toc_noise

  - Table of contents with dotted leaders

• metadata_artifacts

  - Print metadata (Jkt/PO/Frm) in content

• invisible_chars

  - Zero-width spaces, direction markers

• curly_quotes

  - Windows-1252 encoded smart quotes

• ligatures

  - fi/fl/ff ligature characters

Layout (4/4 detected):

• footnotes_inline

  - Footnotes merged into body text (via font size/position heuristics)

• split_tables

  - Tables spanning multiple pages (flag only, no merging)

• header_footer_bleed

  - Headers/footers mixed into content (via PyMuPDF4LLM Layout)

• diagram_heavy

  - Many embedded diagrams/charts

Network (1/3 detected locally):

• archive_org_wrap

  - Wayback Machine URL wrapper (detected via URL pattern)

• auth_required

  - Marketing platform cookie gates (network-level, not detectable locally)

• access_restricted

  - Government/defense access controls (network-level, not detectable locally)

Workflow Integration

When

memory

or

extractor

agent reports failures:

1. Collect failed URLs in a text file
2. Run batch analysis:

   ./run.sh batch failed_urls.txt

3. Review pattern distribution in output
4. Generate combined stress test:

   ./run.sh combine stress_test.pdf

5. Add stress test to extractor's regression suite
6. New patterns get added to

   fixture-tricky

   for future testing

Data Storage

All data is stored in

~/.pi/debug-pdf/

:

• sessions/

  - Individual analysis session JSON files

• fixtures/

  - Generated reproduction PDFs

• last_analysis.json

  - Quick reference to most recent analysis

Dependencies

• pymupdf

  (fitz) - PDF structure analysis

• pymupdf4llm

  - ML-based layout detection for header/footer bleed

• httpx

  - HTTP downloads with redirect handling

• typer

  - CLI interface

• loguru

  - Logging

Sibling skills used:

• fetcher

  - Robust URL downloading with Playwright support

• fixture-tricky

  - Adversarial PDF generation

• extractor

  - Verification of generated fixtures

• agent-inbox

  - Cross-agent notifications

Testing

# Run test suite (24 tests)
python -m pytest tests/test_debug_pdf.py -v

# Generate test fixtures only
python tests/test_debug_pdf.py

Test coverage includes:

• URL validation (security hardening)
• Wayback URL detection and extraction
• Multi-column layout detection
• Header/footer bleed detection
• Split table detection
• Footnote detection
• Full PDF analysis integration

Sanity Check

./sanity.sh

Verifies:

• Python dependencies installed
• Sibling skills available
• Data directory accessible
• CLI commands functional