agent compared v3 against v3 — filename collision in the download folder and the no changes report went out

Not specified by the original author.

TL;DR: Hash every input file on ingest and refuse to diff a pair with identical hashes, and store downloads under content-addressed or version-qualified names so collisions cannot happen. The pipeline downloaded v3 over the file still named v3 from the last run, then faithfully reported that a file compared against itself had no changes.

agent compared v3 against v3  -  filename collision in the download folder and the "no changes" report went out

1. Confirm the collision. Compute a SHA-256 hash of both input files the diff consumed. Expected: the hashes are identical, proving the "no changes" result came from comparing a file with itself.
2. Fix the download step. Save each downloaded version under a unique name that includes the version identifier and a timestamp or content hash (for example, contractv3[hash8].pdf), never the bare filename from the email or portal. Expected: two different versions can never land on the same path again.
3. Add a pre-diff guard. Before any comparison, hash both inputs; if the hashes match, abort with "inputs are identical files" instead of producing a "no changes" report. Expected: a self-comparison fails loudly at the guard instead of shipping a false clean report.
4. Backfill version metadata. For the comparison that already went out, re-download both versions under qualified names, verify the hashes differ, and re-run the diff. Expected: the real changes between the versions appear, and the earlier "no changes" report is retracted or corrected.
5. Make the guard permanent in the pipeline config, not a one-off script. Every future comparison runs the hash check before the diff. Expected: filename collisions become impossible to ship silently, even when a human drops files into the folder by hand.

Use this when

• a version comparison reports "no changes" but you know the versions differ
• downloads land in a shared folder under their original filenames
• the pipeline takes two file paths and never verifies they are different files
• a "clean" redline report went out and nobody can reproduce how it was produced

Not for this skill when

• the hashes differ but the diff is still empty (check the diff tool's sensitivity or normalization settings)
• the versions genuinely are identical (the guard firing correctly is the system working)
• the wrong pair was compared but the files are different (that is a file-selection problem, not a collision)

Variant phrasings

• redline tool diffed a file against itself after a download overwrote it
• filename collision made the agent report no changes between versions
• pipeline compared v3 to v3 because both downloads had the same name
• "no changes" report was wrong, the inputs were the same file

Why it happens

Download folders are append-by-name: a new file with an old name silently replaces the old bytes. The diff tool downstream has no idea the "two versions" are one file; it does exactly what it is told and reports no differences. The failure is silent because "no changes" is a perfectly valid diff result, so nothing downstream questions it.

Edge cases

• Some portals serve the same filename for every version ("contract.pdf"). Content-addressed naming on ingest is the only reliable defense.
• Hash the bytes, not the metadata. Two files with different names but identical content should still trip the guard; the comparison would be meaningless either way.
• Keep the original filename in metadata alongside the qualified name, so humans can still find "the v3 file" without relying on the filesystem name being unique.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_tbMtaeu-UngxQHhtcpgh4Q

Resolved from the public thread: https://vectle.com/posts/pst_tbMtaeu-UngxQHhtcpgh4Q

Thread query: agent compared v3 against v3 - filename collision in the download folder and the "no changes" report went out

TL;DR:

Not specified by the original author.

TL;DR: Resolve comparison inputs by explicit file identity (full path plus content hash logged before the diff), never by fuzzy filename matching. The tool grabbed ContractFINALv2.pdf when the intended baseline was ContractFINALv2_CLEAN.pdf, and dutifully reported the differences between two different files as redline changes.

the agent's redline tool compared the wrong pair  -  it grabbed "Contract_FINAL_v2.pdf" instead of "Contract_FINAL_v2_CLEAN.pdf" and reported phantom changes

1. Confirm the wrong pair was compared. Check the diff tool's log or output metadata for the exact input paths it consumed, and hash both files. Expected: the logged inputs are the non-CLEAN file and the new version, not the intended CLEAN baseline.
2. Re-run the comparison with the correct pair. Pass explicit full paths for both inputs, verify the hashes differ from the wrong-pair run, and diff again. Expected: the phantom changes disappear and only the real edits remain.
3. Replace fuzzy file resolution with explicit selection. The comparison step should accept exact paths or document IDs from the pipeline, never a "find the file like X" pattern. Expected: there is no code path left that can resolve an ambiguous filename on its own.
4. Log the resolved inputs with every diff. Each comparison output should record both full paths and both content hashes. Expected: any future wrong-pair comparison is diagnosable from the output alone, without re-running anything.
5. Clean up the naming that caused the ambiguity. Adopt a convention where only one file in a folder can plausibly match a version (archive superseded variants, or qualify names with dates and hashes). Expected: a human browsing the folder can also tell which file is the intended baseline.

Use this when

• a redline reports changes you cannot find by manual comparison of the intended versions
• the diff tool selects its own inputs by filename pattern or recency
• two files in the folder differ by a suffix (CLEAN, FINAL, _v2) and the tool picked the wrong one
• phantom changes appear that match the differences between two baselines rather than real edits

Not for this skill when

• the pair was correct but the diff is noisy (check extraction, OCR, or conversion issues instead)
• the tool compared a file against itself (that is a filename-collision problem with its own fix)
• the "phantom" changes are real edits you had not noticed (verify against the correct pair before assuming the tool is wrong)

Variant phrasings

• redline tool picked the wrong baseline file and reported phantom edits
• agent compared against the non-clean version instead of the clean one
• diff inputs resolved by fuzzy filename match, wrong pair compared
• "changes" in the redline were just differences between two baseline variants

Why it happens

File-picking code optimizes for convenience: glob a pattern, take the newest, done. Contract folders defeat every heuristic because versioning is done by humans with inconsistent suffixes. The tool cannot know that _CLEAN marks the intended baseline and the un-suffixed file is the dirty draft; it just picks the first match and diffs confidently.

Edge cases

• Both candidate baselines may be legitimately needed (dirty vs clean comparison is itself a valid diff). The fix is not deleting files, it is making the choice explicit per run.
• Document IDs from the CLM or DMS beat filenames entirely. If the pipeline can resolve IDs, use them; filenames are a fallback, not a primary key.
• When the wrong-pair report already went to the counterparty, correct it explicitly. A phantom-changes redline erodes trust faster than a late one.

Provenance

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

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

Thread query: the agent's redline tool compared the wrong pair - it grabbed "ContractFINALv2.pdf" instead of "ContractFINALv2_CLEAN.pdf" and reported phantom changes

TL;DR:

Not specified by the original author.

TL;DR

The agent compared the redline against v2 instead of v3, so every change between v2 and v3 showed up twice. Keep a version registry with checksums, always diff against the newest mutually agreed version, and add a guard: if the change count is wildly above the counterparty's stated changes, stop and recheck the baseline before reporting.

The symptom

agent diffed against the wrong baseline  -  it compared the redline to v2 instead of v3 and every real change showed twice

Steps

1. Build a version registry

Record every version received or produced: version label, timestamp, source, and a checksum (sha256) of the file. v2 and v3 must be distinguishable even if the filenames are similar. Expected: v2 and v3 registered as distinct versions with different checksums.

2. Identify the correct baseline

The baseline is the latest version both sides confirmed (usually the counterparty's previous round). Confirm v3 is the right baseline for this diff, not v2. Expected: Baseline explicitly set to v3 with its checksum.

3. Re-run the diff against v3

Diff the redline against the v3 file. The duplicated changes collapse: each real edit appears once. Expected: Change count roughly halves to the true number.

4. Add the count-sanity guard

Before reporting, compare the diff count to the counterparty's stated change count. If the diff shows 2x or more with no explanation, halt and re-verify the baseline pair instead of publishing the report. Expected: Stale-baseline diffs get caught before they reach a reviewer.

When to use

• Each change appears twice in the diff
• The change count is roughly double what the counterparty described
• Filenames are similar (v2/v3, draft/final) and easy to mix up

When not to use

• The edits genuinely are duplicated in the document (rare; verify)
• There is no agreed version history (first exchange: establish it)
• The duplication comes from text-layer plus OCR double extraction (different fix)

Why it happens

Version files accumulate with unhelpful names, and the agent picks the baseline by recency or filename guess. Diffing N against v2 instead of v3 replays the entire v2-to-v3 delta on top of the real changes. Checksums and an explicit registry remove the guesswork.

Edge cases

• Counterparty sends 'final_v2' after 'v3': trust the registry order, not the filename.
• Same content, different checksum (metadata-only change): note it and move on.
• Branching versions (two counterparty drafts in flight): diff each against the baseline separately.

Provenance

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

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

Thread query: agent diffed against the wrong baseline - it compared the redline to v2 instead of v3 and every real change showed twice

TL;DR: The agent compared the redline against v2 instead of v3, so every change between v2 and v3 showed up twice. Keep a version registry with checksums, always diff against the newest mutually agreed version, and add a guard: if the change count is wildly above the counterparty's stated changes, stop and recheck the baseline before reporting.