# Diagnosis The safest way to approach this is to treat PDF/document parsing, OCR handoff, page ordering, text extraction, tables, encodings, malformed files, resource limits, metadata, partial results, and provenance as a contract problem rather than a prompt-only or one-line patch. From the evidence in the request, the working invariant should be: **Every extracted fragment must retain source provenance and extraction status; unsupported, malformed, image-only or partially parsed content must be explicit rather than silently represented as complete text.** I would keep verified facts separate from hypotheses and would not claim any repository edit, command, external check, or passing test unless it was actually performed. # Evidence and contract map - **Check 1:** MIME/signature detection versus filename extension. Record the current source of truth, observed value/state, expected value/state, and whether the evidence is VERIFIED, LIKELY, or UNKNOWN. - **Check 2:** parser/OCR selection and fallback rules. Record the current source of truth, observed value/state, expected value/state, and whether the evidence is VERIFIED, LIKELY, or UNKNOWN. - **Check 3:** page and block ordering. Record the current source of truth, observed value/state, expected value/state, and whether the evidence is VERIFIED, LIKELY, or UNKNOWN. - **Check 4:** table structure and merged-cell handling. Record the current source of truth, observed value/state, expected value/state, and whether the evidence is VERIFIED, LIKELY, or UNKNOWN. - **Check 5:** Unicode, hyphenation and normalization. Record the current source of truth, observed value/state, expected value/state, and whether the evidence is VERIFIED, LIKELY, or UNKNOWN. - **Check 6:** partial-success/warning representation. Record the current source of truth, observed value/state, expected value/state, and whether the evidence is VERIFIED, LIKELY, or UNKNOWN. - **Check 7:** memory/time limits and malicious/malformed file behavior. Record the current source of truth, observed value/state, expected value/state, and whether the evidence is VERIFIED, LIKELY, or UNKNOWN. # Bounded repair / review plan 1. **Separate detection, parse, OCR, normalization and provenance stages**. Keep the change at the narrowest boundary that owns the contract; do not spread policy into prompts, retries, UI code, or unrelated services just to make the symptom disappear. 2. **Return typed per-page/per-block status rather than one global success flag**. Keep the change at the narrowest boundary that owns the contract; do not spread policy into prompts, retries, UI code, or unrelated services just to make the symptom disappear. 3. **Apply OCR only when evidence shows text is absent/insufficient and preserve OCR provenance**. Keep the change at the narrowest boundary that owns the contract; do not spread policy into prompts, retries, UI code, or unrelated services just to make the symptom disappear. 4. **Bound parser memory/time and isolate unsafe inputs**. Keep the change at the narrowest boundary that owns the contract; do not spread policy into prompts, retries, UI code, or unrelated services just to make the symptom disappear. 5. **Maintain golden fixtures for columns, tables, scans, Unicode and malformed documents**. Keep the change at the narrowest boundary that owns the contract; do not spread policy into prompts, retries, UI code, or unrelated services just to make the symptom disappear. # Concrete implementation pattern Use one versioned boundary object that carries the canonical identity/state needed by the next layer. Validate it once at the authority boundary, return typed failures instead of ambiguous booleans, and make retries consume those typed outcomes rather than replaying the whole workflow blindly. Where an external or irreversible side effect exists, persist the authorization/idempotency state before execution and reconcile the final result after execution. Where the task is a review rather than a code repair, use the same structure as an evidence gate: requirement → evidence → status → owner → next action. For this skill specifically, the boundary must preserve document confidentiality, sandbox/resource limits, accepted file formats, provenance requirements, and downstream data contracts. A local adapter or validator can normalize representation, but it must not silently manufacture missing authority, evidence, provenance, or business values. Unknown state should remain UNKNOWN or follow an explicitly documented safe fallback. # Deterministic validation matrix The remaining details should be verified from the repository or supplied evidence before any production change.