DEBUGGING_WORKFLOW.md

# PDF Debugging Workflow

This guide details how to use the PDF Inspector tool to diagnose and remediate common PDF accessibility issues.

## 1. Initial Compatibility Check
**Goal**: Determine if the document requires major remediation before detailed analysis.

1.  **Upload the PDF**: Use the file uploader or select an example from the list.
2.  **Run Single Page Analysis**: Click "Analyze".
3.  **Check for Alerts**: Look for the "Accessibility Alert" box at the top of the summary.
    *   **Untagged Document**: If you see this, the document lacks the "Structure Tree" required for screen readers.
        *   *Remediation*: Open the source file (Word/PPT) and "Save as PDF" with tags enabled, or use Adobe Acrobat Pro's "Autotag" feature.
    *   **Scanned Page**: If you see this, the page is an image with no selectable text.
        *   *Remediation*: Perform Optical Character Recognition (OCR) using Adobe Acrobat or a similar tool.

## 2. Detailed Single-Page Inspection
**Goal**: Verify reading order and content types on a specific page.

1.  **Visual Inspection**: Look at the "Analysis Results" image.
    *   **Red Boxes**: Indicate detected text blocks.
    *   **Numbers**: Show the reading order.
2.  **Verify Reading Order**:
    *   Does the order (1, 2, 3...) follow the logical flow of the document?
    *   *Issue*: If columns are read left-to-right across the page instead of down the column, the reading order is broken.
    *   *Fix*: This usually requires manual retagging in Acrobat (Order panel).
3.  **Check for Artifacts**:
    *   Are headers/footers marked as text blocks? (They should generally be artifacts/ignored by screen readers).

## 3. Advanced Diagnostics
**Goal**: Deep dive into specific issues using the "Advanced Analysis" tab.

### Content Stream Inspector
*   **Use when**: Text looks correct visually but copies weirdly or reads wrong (e.g., "fi" ligaure issues).
*   **Action**: Select a block and click "Extract Operators".
*   **Look for**: `TJ` or `Tj` operators showing garbled characters or strange spacing adjustments.

### Screen Reader Simulator
*   **Use when**: You want to "hear" what a user hears.
*   **Action**: Select "NVDA" and click "Generate Transcript".
*   **Check**:
    *   Are headings announced as "Heading Level X"?
    *   Is alt text read for images?
    *   Is the reading order intelligible?

### Paragraph Detection
*   **Use when**: Text seems run-on or broken into too many fragments.
*   **Action**: Click "Analyze Paragraphs".
*   **Check**:
    *   **Visual vs. Semantic**: Large discrepancies suggest the `<P>` tags don't match the visual layout, which can confuse users navigating by paragraph.

### Structure Tree Visualizer
*   **Use when**: The document is tagged, but navigation is broken.
*   **Action**: Click "Extract Structure Tree".
*   **Check**:
    *   Hierarchy depth.
    *   Correct nesting (e.g., `L` -> `LI` -> `LBody`).

## 4. Batch Analysis for Large Documents
**Goal**: Identify problematic pages in a long report.

1.  **Go to Batch Analysis Tab**.
2.  **Run Batch**: Analyze 50-100 pages.
3.  **Review the Report**:
    *   **Issues Found**: Look for "Scanned Pages" or "Garbled Text".
    *   **Page List**: Use the list of page numbers to targeting your remediation efforts.

## Summary Checklist
- [ ] Document is Tagged (`/StructTreeRoot` exists)
- [ ] Text is selectable (not an image/scan)
- [ ] Reading order is logical (columns handled correctly)
- [ ] Images have Alt Text (or are marked as artifacts)
- [ ] Headings use Heading tags (`<H1>`, `<H2>`), not just bold text.