agent cannot parse whatsnew release notes file: parsing failed with error and the workflow broke

TL;DR

When an agent run to parse the whatsnew file hits this failure - parsing failed and the workflow broke - do not retry the same step blindly. First check the real state in the release tooling to learn whether the step already took effect, then make the parser tolerant and the failure cheap: read the file as bytes, decode explicitly as UTF-8, parse with a real parser for the format rather than string splitting, validate against the expected shape, and on failure report the exact line or key instead of aborting the whole release. That sequence prevents duplicate uploads, corrupted release state and silent half-finished releases.

agent cannot parse whatsnew release notes file: parsing failed with error and the workflow broke

Use this when

• An automated release run to parse the whatsnew file failed with this pattern.
• The workflow uses the release tooling and the failure appeared mid-run, after earlier steps may already have applied.
• You are hardening a mobile release agent before its next unattended run.

Not for this skill when

• A human running the same step manually in a terminal or console succeeds. That points at the underlying tool, not the agent wrapper.
• The store rejected the release on policy or metadata grounds. That is a store review issue, not an agent reliability failure.

Steps

1. Preserve the exact failing file unchanged as a test case before editing anything. Verify: a copy of the failing file is saved with the run records
2. Reproduce the parse locally and capture the precise error: encoding, line, column or key it names. Verify: the error is reproduced and its position in the file is known
3. Fix the reading path for whatsnew release notes file: open as bytes, decode as UTF-8 explicitly, and parse with the format real parser, handling emoji, accents and special characters as normal content. Verify: the saved failing file parses without error
4. Validate the parsed result against the expected shape, listing missing or mistyped fields instead of failing on the first one. Verify: validation reports all shape problems in one pass, or confirms the shape is complete
5. Make parse failure survivable: the workflow reports the file and position and halts before any store change, rather than crashing mid-release. Verify: a deliberately broken test file produces a clear report and zero store changes
6. Re-run the workflow to parse the whatsnew file with the original file. Verify: the run proceeds past parsing and completes or reaches the next genuine step
7. Record the fix in the release runbook or the CI job notes, naming the error, the value or setting that changed, and the date, so the next release engineer does not re-diagnose it from scratch. Verify: the runbook or job notes contain an entry for this error that a teammate can find by searching the error text

Why it happens

Release files are written by humans and other tools: emoji, smart quotes, stray delimiters and locale text are normal content, not corruption. A parser that assumes clean ASCII input, or that splits on characters the content legitimately contains, fails on real release material.

In practice this failure is rarely a one-off. It tends to recur at the worst point in the release cycle, when a certificate, a toolchain, a store policy or a team process has quietly changed since the last successful release and nobody connected that change to the release pipeline. That is why the steps above insist on reading the actual store, portal or build state at each point instead of trusting configuration files or memory: the configuration usually describes the release the team intended to ship, while this error describes the release the systems actually see. Once the immediate upload or build is unblocked, treat the underlying drift as the real defect. Pin the toolchain version, expiry date, identifier or policy value that caused it in the release checklist, and add the cheapest automatic check that would have caught it before submission day, for example a preflight lane that validates signing, versions and metadata lengths before the full archive runs. A release pipeline that fails in preflight costs minutes; the same failure discovered at submission costs a day.

Variants and edge cases

agent failed to parse the whatsnew file reliability playbook

The workflow-hardening phrasing: state checks, budgets and resumability for this step. When you land on this skill from that phrasing, start at step 1 rather than jumping to the most dramatic fix: the early steps are cheap state checks that confirm you are solving the failure you actually have, and they take minutes compared with a rebuild or a store-side change you cannot undo.

the release tooling agent workflow failure recovery

The recovery phrasing: establish real store state first, then resume without duplicating applied steps. When you land on this skill from that phrasing, start at step 1 rather than jumping to the most dramatic fix: the early steps are cheap state checks that confirm you are solving the failure you actually have, and they take minutes compared with a rebuild or a store-side change you cannot undo.

Edge case: partial application

The hardest variant of every agent failure is the half-applied release. Always reconcile store state before resuming, even when the log looks clean. When you land on this skill from that phrasing, start at step 1 rather than jumping to the most dramatic fix: the early steps are cheap state checks that confirm you are solving the failure you actually have, and they take minutes compared with a rebuild or a store-side change you cannot undo.

Provenance

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