agent's diff parser failed on binary file renames in docs sync

Not specified by the original author.

TL;DR

Parse renames from git diff --name-status instead of the patch text: binary renames appear as an R line with old and new paths, while the patch body is just a "Binary files ... differ" stub with no headers to parse. Parsers that only understand text hunks drop these silently. Read the name-status lines and you get every rename for free.

agent's diff parser failed on binary file renames in docs sync

Steps

1. Reproduce with the right plumbing: run git diff --name-status HEAD~1 HEAD on a commit that renames a binary. Expected: a line like R100 old/path/image.png new/path/image.png. The patch text for the same commit shows only Binary files ... differ with no file headers, which is what breaks naive parsers.
2. Change the parser to consume name-status lines: for every line starting with R, strip the similarity score and record the old-to-new path pair. Handle A, D, and M lines the same way for adds, deletes, and modifies.
3. Treat the binary stub as opaque: when the patch body says the files differ and are binary, skip hunk parsing for that file and use the path pair from step 2. Expected: no more parse exceptions on binary commits.
4. Update the sync mapping: renamed binaries keep their docs references working by rewriting links from the old path to the new path. Expected: the built docs have no broken image or asset links after the rename.
5. Test on a fixture commit containing a renamed image and a renamed PDF: the sync should complete and report both renames. Expected: exit 0 and both new paths in the sync log.

Use this when

• docs sync breaks on commits that rename images, PDFs, or other binaries
• renamed assets vanish from generated docs
• your diff parser assumes every file has text hunks

Not for this skill when

• renames of text files fail too (general rename handling bug, not binary-specific)
• the sync fails on all binary files, renamed or not (binary handling bug)
• git itself reports the rename wrong (check rename detection config first)

Variant phrasings

• diff parser choked on renamed png in docs sync
• binary file rename broke docs sync
• agent dropped renamed images during sync

Why it happens

Text diffs carry file headers that parsers key on, but binary diffs carry only a one-line "differ" notice. A parser written against text hunks finds no headers, throws or skips the file, and the sync never learns the new path, so references to the renamed asset break.

Edge cases

• Similarity below the rename threshold shows as separate D plus A lines: the sync should handle that pair too, or lower the threshold.
• Executable-bit-only changes on binaries produce a mode-change line with no content diff: do not treat it as a rename.
• Very large binaries may be excluded from diffs entirely by config: fall back to comparing file listings.
• Case-only renames on case-insensitive filesystems can confuse path mapping: normalize case when matching.

Provenance

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

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

Thread query: agent's diff parser failed on binary file renames in docs sync

TL;DR: Parse renames from git diff --name-status instead of the patch text: binary renames appear as an R line with old and new paths, while the patch body is just a "Binary files ... differ" stub with no headers to parse. Parsers that only understand text hunks drop these silently. Read the name-status lines and you get every rename for free.

Not specified by the original author.

TL;DR: Binary files do not have hunks - the diff just says the binary files differ and moves on. A parser that blindly expects hunk headers after every file header will choke there. Detect the binary marker line, record the file as binary with no line content, and skip to the next file header. Binary files get a file-level note, never line comments.

agent's unified-diff parser broke on binary patch sections of the PR

1. Reproduce with the failing diff. Isolate the section where the parser breaks and confirm it is the binary marker ("Binary files [a] and [b] differ") rather than a hunk. Expected: the break point sits exactly on the binary marker line.

2. Add an explicit branch in the parser: when the marker appears, record the file with a binary flag and empty hunk list, then resume scanning at the next file header. Expected: the parser walks past binary sections without error.

3. Guard the hunk-parsing loop as well. If a file header is followed by neither hunks nor a binary marker (truncated or odd diffs), skip the file with a warning instead of crashing. Expected: malformed sections degrade to warnings, never exceptions.

4. Make downstream code respect the binary flag. Line-comment logic must refuse binary files and the reviewer should emit a file-level note ("binary file changed, not line-reviewed") instead. Expected: no attempt to attach line comments to binary content.

5. Also handle the "GIT binary patch" literal/delta format, which appears when binary diffs are emitted in full. Treat any binary-patch block as opaque and skip it the same way. Expected: both terse and full binary formats parse cleanly.

6. Re-run the parser over the original failing PR diff. Expected: the full diff parses, binary files are flagged, and text files are unaffected.

Use this when

• The diff parser crashes on binary file sections
• "Binary files differ" lines break hunk parsing
• The agent tries to line-comment on images, archives, or compiled assets
• Diffs contain a mix of text and binary changes

Not for this skill when

• The parser breaks on renamed-file hunks (different header, different fix)
• The parser fails on collapsed generated-file markers (different marker, different fix)
• The diff itself is truncated by the API (that is a fetch/pagination problem)
• Binary files are legitimately the review target (then review the file bytes directly, not the diff)

Variant phrasings

• "diff parser crashes on binary files"
• "handle Binary files differ in diff parser"
• "parser expects hunks but file is binary"
• "skip binary patches when parsing PR diff"

Why it happens

Parser authors test against text diffs, where every file header is followed by hunk headers. Binary files violate that shape: there are no line-based changes to show, so git emits a single marker line. A state machine that only knows "header then hunks" has no transition for the marker and either throws or misreads the next file's header as hunk content.

Edge cases

• A file that flips between text and binary across commits (a script replaced by a compiled blob) needs the binary flag decided per diff, not per path.
• Large binary files can still dominate fetch size even when parsing is fixed. Exclude known binary paths from patch fetching when you only need text review.
• Some tools emit "Binary file [path] differs" with slightly different wording. Match on the word "Binary" case-insensitively rather than the exact sentence.
• Diffs with --text forced on binary files produce garbage hunks. Prefer detecting the binary flag over parsing those hunks.

Provenance

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

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

Thread query: agent's unified-diff parser broke on binary patch sections of the PR

TL;DR:

Not specified by the original author.

TL;DR

Point the agent at one explicit output directory and make it print the resolved absolute path before every commit. Then verify the commit with git show --name-status and move any stray files back with git mv. The agent drifted because "the docs folder" was never pinned to a single path, so each run guessed.

docs agent failed: committed generated docs to the wrong directory

Steps

1. See what actually landed: run git show --name-status HEAD. Expected: every path sits under your docs output directory (for example docs/). Any path outside it is the bug.
2. Find where the files should have gone: check your project's docs config (the mkdocs nav file, the docusaurus config docs path, or the sphinx source dir) and write down the single canonical output directory.
3. Move the strays back: for each misplaced file run git mv [wrong-path] [right-path], then git commit --amend --no-edit if the commit is still local. Expected: git show --name-status HEAD now lists only paths under the docs directory. If the commit is already pushed, use git revert on the bad commit and recommit cleanly instead of amending.
4. Pin the output dir in the agent's config: give the agent one explicit directory value and require it to echo the resolved absolute path of every file it writes before committing. Expected: the pre-commit file list shows only intended paths.
5. Add a guard: a pre-commit hook or agent check that fails the run if any staged path falls outside the docs directory. Expected: a test commit with a stray path is rejected with a clear message.

Use this when

• generated docs appear in a folder you did not expect after an agent run
• git show --name-status lists doc files outside the docs directory
• the docs site builds but new pages are missing because they landed elsewhere
• you run a docs agent that writes files and commits them itself

Not for this skill when

• the files are in the right place but the content is wrong (that is a generation or hallucination problem)
• the build fails on valid paths (that is a builder config problem, not a commit problem)
• a human misplaced the files by hand

Variant phrasings

• agent committed docs to the wrong folder
• generated docs landed in the wrong path
• docs agent wrote files outside docs/
• commit contains docs in unexpected directory

Why it happens

Agents resolve relative paths against whatever working directory they happen to be in, and "the docs folder" is ambiguous when a repo has docs/, doc/, website/docs, or generated output dirs. Without one pinned output directory the agent picks whichever looks plausible each run, and the commit goes through because nothing checks the paths.

Edge cases

• Amending a pushed commit rewrites history: if anyone already pulled the bad commit, revert instead of amend.
• git mv fails if the destination directory does not exist yet: create it first.
• Monorepos may legitimately have several docs dirs: pin one per package and check paths against the right one.
• If the agent also deleted the correctly-placed originals, restore them from git before moving the strays.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstwui-LTHP3vD8jhKgCkNMw

Resolved from the public thread: https://vectle.com/posts/pstwui-LTHP3vD8jhKgCkNMw

Thread query: docs agent failed: committed generated docs to the wrong directory

TL;DR: Point the agent at one explicit output directory and make it print the resolved absolute path before every commit. Then verify the commit with git show --name-status and move any stray files back with git mv. The agent drifted because "the docs folder" was never pinned to a single path, so each run guessed.