## TL;DR
Make the file boring before the agent reads it, and make the agent honest when it still cannot. Normalize merged cells in the new hire spreadsheet away with a deterministic pre-processing step that converts the input into a clean tabular form, validate the result row by row, and have the agent halt with a precise row-level report on anything left ambiguous instead of guessing or crashing the whole workflow.

```text
agent cannot parse new hire spreadsheet with merged cells: parsing failed with error and the workflow broke
```

## Use this when
- Agent runs repeatedly break while reading the new hire spreadsheet, even though humans can read the file fine.
- The files come from people or exports that vary in layout, formatting, or completeness between runs.
- Each failure stops the entire workflow, including hires whose rows are perfectly clean.

## Not for this skill when
- The file is a one-time manual creation and the process is moving to an API feed. Invest in the feed instead of the parser.
- Parsing succeeds but the values are wrong due to column shifts. That needs layout validation, covered in the steps as a check.

## Steps
1. Collect the failing files from recent runs and characterize the variations the parser met, layout changes, merged or wrapped cells, extra header rows, inconsistent columns, or encoding quirks, using the actual files rather than descriptions of them. Verify: the variation list is built from real failing examples
2. Build a deterministic pre-processor that converts the raw input into a canonical table: it resolves merged cells in the new hire spreadsheet by explicit rules, normalizes headers to the agreed column names, and emits one clean record per hire with the source row number attached. Keep this logic in code, not in model judgement. Verify: the pre-processor converts every collected failing file into the canonical form or reports why not
3. Validate the canonical table before the agent sees it: required columns present, key fields non-empty and unique, dates and codes in their expected formats, and row counts reconciled with the source file. Failures produce a row-level report for a human, not a workflow crash. Verify: the validator catches seeded defects with correct row numbers
4. Change the agent contract: the agent consumes only the canonical table, processes hires independently so one bad row cannot break the cohort, and records per-hire outcomes that the workflow aggregates at the end. Verify: a test run with one bad row completes all clean rows and reports the bad one
5. Run the full workflow on the most recent real file and confirm the invite the user to GitHub step proceeds for the clean hires and the exception report matches what a human finds in the original file. Verify: workflow results and the exception report agree with a manual spot check
6. Push the standard upstream: publish the canonical template for whoever produces the file, with the validation rules stated plainly, and track exception rates per producer so the worst inputs get coaching or a direct system feed. Verify: the template is published and exception rates are being recorded

## Why it happens
Files produced by people and office tools are presentation artefacts, not data contracts: they carry merged cells in the new hire spreadsheet and other layout choices that mean nothing to a human reader and everything to a parser. Asking a language model to absorb that variability at runtime mixes two jobs, format recovery and provisioning judgement, and the workflow breaks whenever the format wins. A deterministic pre-processor owns the format, validation owns the truth checks, and the agent owns only the decisions it is good at, which is why the combination survives real-world files that defeat any single layer alone.

## Variants and edge cases
### Merged cells carry real meaning
Where merged headers group columns, encode the grouping in the pre-processor mapping explicitly and test it whenever the producer template changes.

### Files arrive as scans or PDFs instead
Add a document extraction stage with confidence scores and route low-confidence rows to human review rather than letting the agent read raw extraction text as fact.

### Producer cannot change their export
Keep the pre-processor tolerant for that producer as a named profile, and isolate their quirks so other producers get the strict fast path.

Compatibility: Applies to agent workflows consuming new hire spreadsheet files for provisioning. Requires workflow editor and scripting access for the pre-processor.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_ek2LOXStfqU1Elt-uiHZeg