## TL;DR
Constrain the notes format or parse defensively with fallbacks: markdown tables in human notes vary in column order, missing cells, and prose between tables, so a strict parser fails on the first irregular note. Extract tables loosely, map columns by header names rather than positions, treat unparseable notes as a flagged remainder for review instead of aborting the batch, and propose a lightweight template for future notes.

```text
parser failed on unstructured run notes in markdown tables and produced a parsing failure
```

## Use this when
- The run or call fails with this symptom: parser failed on unstructured run notes in markdown tables and produced a parsing failure.
- You are working on an agent extracting results from researchers' markdown run notes and the failure repeats on the same run or configuration.
- You need the failing run, call, or stage isolated before changing code or thresholds.

## Not for this skill when
- Notes that are pure prose with no tables at all, where extraction is a reading task, not a parsing task.
- The error text names a different tool, stage, or root cause. Match the verbatim error first and use that skill.

## Steps
1. Survey the notes corpus and catalogue the table shapes actually present: headers, column orders, and irregularities. Verify: the real format variety is documented
2. Rewrite extraction to find tables by header names and tolerate missing optional columns and extra prose. Verify: most notes parse under the tolerant reader
3. Collect notes that still fail into a review list with the failing table shown, instead of failing the batch. Verify: failures are isolated and visible
4. Publish a short note template for the team and confirm new notes follow it by re-running extraction. Verify: new notes parse at a higher rate

## Variant phrasings
### parser failed unstructured run notes markdown tables
The verbatim phrasing.
### agent parse experiment notes markdown table irregular fix
The tolerant phrasing.
### run notes extraction parsing failure header mapping agent
The header phrasing.

Compatibility: Agent parsers reading free-form experiment notes in markdown

## Why it happens
Free-form notes are written for humans, who repair irregularities unconsciously while reading. A positional, strict parser has no such repair, so ordinary variation, a swapped column, an empty cell, a comment line, reads as corruption. Tolerance plus a template fixes both the backlog and the future.

## Edge cases / pitfalls
- Numbers written as ranges or approximations need a representation in the output, not a silent drop.
- Tables inside code fences are examples, not data; the extractor must skip fenced blocks.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_8a_O-rAtr2OOHgf8IzLXsg