agent flagged every cross-reference as changed after the counterparty renumbere

Not specified by the original author.

TL;DR

The counterparty renumbered the sections without changing any clause text, and the agent flagged every cross-reference as changed. Align clauses between versions by text similarity instead of by number, emit the renumbering as a single mapping (old 4.2 is now 5.1), and verify the clause texts are identical before calling it renumber-only.

The symptom

agent flagged every cross-reference as changed after the counterparty renumbered the sections  -  the numbers moved but no clause text changed

Steps

1. Align clauses by text, not by number

Parse each version into (section number, clause text) pairs. Match pairs across versions by text similarity (normalized text, ignoring the number). Renumbered clauses match on text. Expected: Each clause in v1 matched to its v2 counterpart despite different numbers.

2. Emit a single renumber map

From the alignment, produce the mapping: 4.1 to 5.1, 4.2 to 5.2, and so on. Present this once instead of flagging each reference. Expected: One renumber table covering all moved sections.

3. Verify the texts are identical

For each aligned pair, diff the clause texts. If all diffs are empty, the change is renumber-only. Any non-empty diff is a real edit hiding inside the renumbering: report it. Expected: Empty text diffs across the board, or a short list of real edits.

4. Rewrite references through the map for the report

Show cross-references resolved through the map so reviewers see 'see Section 5.1 (formerly 4.2)'. Do not list each reference as a change. Expected: References readable under the new numbering with old numbers noted.

When to use

• Every cross-reference is flagged but clause texts are unchanged
• The counterparty renumbered sections, articles, or exhibits
• The diff is number-driven rather than text-driven

When not to use

• Clause text actually changed along with the numbers (report the text edits)
• References point at sections that no longer exist (broken links, different issue)
• Numbering is unchanged (different cause)

Why it happens

Cross-references embed section numbers, so a renumbering touches every reference string. A string diff cannot tell 'number moved' from 'meaning changed'. Aligning on clause text separates the two: identical texts mean the renumbering is the whole story.

Edge cases

• Split or merged sections: one-to-many alignments need human review; do not force a map.
• Exhibit renumbering (Exhibit A to Exhibit 1): same technique, separate map.
• References inside defined terms: apply the map there too, consistently.

Provenance

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

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

Thread query: agent flagged every cross-reference as changed after the counterparty renumbered the sections - the numbers moved but no clause text changed

TL;DR: The counterparty renumbered the sections without changing any clause text, and the agent flagged every cross-reference as changed. Align clauses between versions by text similarity instead of by number, emit the renumbering as a single mapping (old 4.2 is now 5.1), and verify the clause texts are identical before calling it renumber-only.

Not specified by the original author.

TL;DR

Resolve citations against the fully-amended text, never the base document. Build a versioned clause map keyed by (section, amendment chain) and apply every amendment in effective-date order before the agent looks up any cross-reference. "As amended by Amendment No. 2" is a pointer into the post-amendment document, so resolving it against the original text silently reads wording that is no longer operative.

clause points to "Section 4.2 of the Original Agreement as amended by Amendment No. 2"  -  the agent resolved it against the unamended text

Steps

1. Index every amendment in effective-date order, parsing the effective date from the amendment text itself, not from the filename or upload time. Expected: each amendment has an effective-date field; the order matches the legal sequence

2. Build a layered section map: for each numbered section, stack the base text then each amendment's replacement text on top. Expected: "Section 4.2" resolves to a stack of versions, each tagged with the amendment that produced it

3. Parse the citation's amendment qualifier ('as amended by Amendment No. 2') as a version selector, and resolve the citation to that layer of the stack. Expected: the resolved text comes from the Amendment 2 version of Section 4.2, not the base

4. Add a regression check that diffs the resolved text against the base text whenever a qualifier is present; if they are identical, the qualifier was ignored and the resolution is flagged. Expected: every citation resolution logs which amendment layer it came from

5. Re-run the full extraction suite after this change and confirm no citation with an amendment qualifier points at raw base text. Expected: zero qualifier-bearing citations resolve against the unamended text

Use this when

• A citation names an amendment: "as amended by Amendment No. 2", "as restated by Amendment 3".
• The agent extracts clauses from agreements that have an amendment chain.
• Resolved text looks subtly wrong but matches the original agreement.
• You are auditing an extraction pipeline and want citation-resolution correctness.

Not for this skill when

• The contract is a single version with no amendments.
• The reference carries no amendment qualifier; it is a plain section pointer.
• You need legal interpretation of what the clause means, not a fix for which text was resolved.
• The wrong text came from OCR or PDF parsing, not from version selection.

Variant phrasings

agent resolved against the original agreement instead of the amended version

clause citation ignores the amendment chain

"as amended by" qualifier dropped by the extraction agent

cross-reference points at pre-amendment wording

Why it happens

Agents usually resolve citations eagerly against the base document and apply amendments in a separate, later pass (or never). Because the base and the amended version share section numbers, the wrong hit looks exactly right: the section exists, the text is plausible, and nothing errors. The failure is silent by construction.

Edge cases

• An amendment restates only part of a section; the untouched paragraphs of the base text are still live. Resolve paragraph-level, not section-level.
• The qualifier names an amendment the agent does not have. Raise a missing-document warning; never guess what the amendment said.
• Effective date and signing date disagree. Order by effective date; use signing date only as a tiebreak.
• Multiple amendments touch the same section. The qualifier selects one layer; without a qualifier, the latest effective layer wins.

Provenance

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

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

Thread query: clause points to "Section 4.2 of the Original Agreement as amended by Amendment No. 2" - the agent resolved it against the unamended text

TL;DR: Resolve citations against the fully-amended text, never the base document. Build a versioned clause map keyed by (section, amendment chain) and apply every amendment in effective-date order before the agent looks up any cross-reference. "As amended by Amendment No. 2" is a pointer into the post-amendment document, so resolving it against the original text silently reads wording that is no longer operative.

Not specified by the original author.

TL;DR

The payer did not change; the bank changed how it spells the payer. When the memo descriptor moved from a short form to the full legal name, every string-similarity feature the matcher relied on fell at once, and confidence collapsed across that counterparty's payments. Teach the matcher that descriptors are unstable labels, not identities: normalise memo text (case, punctuation, legal suffixes such as LLC and Inc, common abbreviations) before scoring, maintain an alias table that maps observed descriptors to the counterparty master record, and weight amount, date and any remittance reference more heavily than the memo for known counterparties. Backfill the alias from the old and new descriptors, rematch the affected population, and add descriptor-drift monitoring: a sudden confidence drop concentrated on one counterparty is a descriptor event until proven otherwise.

agent's match confidence collapsed after the bank memo descriptor changed from NET-30 ACME to ACME INDUSTRIES LLC

Use this when

• Match rates or confidence for one counterparty's payments fall sharply after a bank or processor change.
• The bank memo shows a new form of a familiar name, such as a full legal entity name replacing a short trading name.
• Amounts and timing of the payments are unchanged; only the text changed.

Not for this skill when

• Payments from a genuinely new counterparty are unmatched. Onboard the counterparty properly instead of aliasing it to a similar name.
• Confidence fell across all counterparties at once. That suggests a matcher or data pipeline change, not one descriptor.

Steps

1. Quantify the drop: match confidence and rates for the counterparty before and after the descriptor change date. Verify: the collapse is bounded to the counterparty and the change date
2. Collect the old and new descriptor strings from bank memos and confirm both belong to the same counterparty via amounts, references or the counterparty itself. Verify: both descriptors are proven to be the one payer
3. Add both forms to the counterparty alias table and set the normalisation rules for legal suffixes, punctuation and case. Verify: the alias and normalisation are saved in the matching configuration
4. Rematch the affected payments and review a sample of the newly matched items by hand for correctness. Verify: the sampled matches are genuinely the counterparty's payments
5. Enable drift monitoring: alert when one counterparty's average confidence drops sharply week on week. Verify: the monitor is active and the incident is logged with its resolution

Variant phrasings

match confidence collapsed bank memo descriptor changed ACME legal name

The descriptor-change symptom.

bank descriptor normalisation alias table counterparty matching agent

The alias and normalisation phrasing.

fuzzy matcher descriptor drift legal suffix LLC Inc normalise fix

The normalisation detail search.

Compatibility: Agent and auto-match engines in reconciliation tools and ERP cash application, consuming bank memo and descriptor fields from BAI2, MT940, CAMT and open banking feeds.

Why it happens

Bank descriptors are presentation text owned by the bank's systems, and banks reformat them during core upgrades, processor switches and compliance changes that force legal names. A matcher that leans on raw string similarity inherits all that instability as if counterparties were changing identity. The payments themselves never changed - same amounts, same cadence, same references - which is why anchoring identity in an alias table plus transactional features survives descriptor drift that destroys text-only matching.

Edge cases / pitfalls

• Legal suffix normalisation can over-merge distinct entities in a group (an LLC and an Inc with the same root name); keep group entities as separate aliases with corroborating features required.
• Descriptor changes sometimes accompany a genuine payer change after an acquisition; corroborate with references before aliasing.
• Review the alias table quarterly: stale aliases for dead counterparties create false-match risk.

Provenance

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

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

Thread query: agent's match confidence collapsed after the bank memo descriptor changed from NET-30 ACME to ACME INDUSTRIES LLC

TL;DR: The payer did not change; the bank changed how it spells the payer. When the memo descriptor moved from a short form to the full legal name, every string-similarity feature the matcher relied on fell at once, and confidence collapsed across that counterparty's payments. Teach the matcher that descriptors are unstable labels, not identities: normalise memo text (case, punctuation, legal suffixes such as LLC and Inc, common abbreviations) before scoring, maintain an alias table that maps observed descriptors to the counterparty master record, and weight amount, date and any remittance reference