## TL;DR
Jupytext round-trips (notebook to script and back) fail when the jupytext version disagrees with the notebook format version, or when the agent reads with one tool and writes with another. Use jupytext for both directions (`jupytext --to py` and back), pin the jupytext version in the agent's environment, and verify the round-trip with a hash of the cell sources before and after. Format fidelity is the acceptance test, not just 'it produced a file'.

```text
agent failed to round-trip the notebook through jupytext, parse error
```

## Use this when
- An agent converts ipynb to py and back and the result is broken.
- The round-trip loses cells, metadata, or outputs.
- Jupytext versions differ between environments.

## Not for this skill when
- One-direction conversion fails. Debug that direction alone.
- A human uses jupytext in the UI. Check the pairing config.

## Steps
1. Pin jupytext: same version everywhere the agent runs. Verify: `jupytext --version` matches.
2. Round-trip with jupytext both ways: `--to py` then `--to ipynb`. Verify: both commands succeed.
3. Compare cell sources before and after (hash them). Verify: sources are identical.
4. Check metadata survival: kernelspec, tags, key custom fields. Verify: nothing load-bearing was lost.
5. Bake the round-trip check into the agent's tests. Verify: the test fails on version skew.

## Variant phrasings
### jupytext round trip failed
Short form. Pin versions, verify fidelity.

### ipynb py ipynb conversion broken
The direction phrasing. Same tool both ways.

### jupytext parse error agent
The error phrasing. Version skew is the suspect.

Compatibility: jupytext 1.14+, nbformat 5.x. Percent and light formats are the common round-trip targets.

## Why it happens
Jupytext maps between two formats with different expressiveness, and the mapping evolves with versions: a script format written by jupytext 1.16 may use markers that 1.13 cannot parse back. Agents that shell out to whatever jupytext is installed get whatever version the environment happens to have, so round-trips break on version skew that nobody pinned. Using one tool both ways plus a fidelity check makes the round-trip deterministic.

## Edge cases / pitfalls
- Outputs do not survive to .py by default. That is expected, not a round-trip failure; compare sources, not outputs.
- Custom cell metadata may not map to the script format. Check what your format preserves.
- The `--sync` mode is for paired workflows; the agent should use explicit conversions for clarity.
- Test round-trips on real notebooks with widgets and magics, not just clean examples.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_VV_ZUzo1Ika1lRe9T7bLbQ