Version Chaos Untangler Skill
Six copies of the contract: email attachments, two drives, someone's desktop, one renamed -final-JT-edits. Two have diverged — different edits on a shared ancestor — and the team is now editing in parallel universes. Untangling is forensic then structural: census every copy (where, modified-when, by-whom), establish the canonical defensibly (newest is not automatically rightest), merge what diverged, then kill the conditions — one home, links-not-attachments, and platform version history doing what filename suffixes failed to do.
What This Skill Produces
- The version census — every known copy: location, modified date, editor, size/diff signals
- The canonical verdict — which version wins and why (the lineage argument, not just the timestamp)
- The merge plan — the divergent edits reconciled, with the who-confirms list for judgment conflicts
- The single-source install — one home, the redirect of every old copy, and the links-only norm
Required Inputs
Ask for these if not provided:
- The copies — everywhere it lives (search email attachments by filename, both drives, ask the usual suspects); the census is only as good as the hunt
- The stakes — a contract mid-negotiation and a team doc carry different merge rigor; legal-adjacent docs get the careful version
- The editors — who touched it recently; diverged edits need their authors for the judgment calls
- The platform reality — where the canonical should live (the versioned platform — cloud doc or drive with history — not email, not desktops)
Framework: The Untangle Rules
- Census before choosing: list every copy with modified-date and editor before any verdict — the loudest "mine is latest" claim is wrong often enough that the census is not optional. Email attachments are copies-at-a-timestamp, and every send forked the universe.
- Canonical is lineage, not timestamp: the winner is the copy containing the most confirmed-wanted edits — usually but not always the newest. The tell for divergence: two copies both modified after their common ancestor. When found, neither is canonical yet; the merge output is.
- Merge by diff, confirm by author: compare divergent copies section-by-section (platform compare tools where they exist); mechanical differences merge directly, judgment conflicts (two different edits to the same clause) go to their authors by name. The merge doc lists every judgment call and who confirmed it — for legal-adjacent docs, that list is the audit trail.
- Kill the old copies loudly: every non-canonical copy gets replaced by a pointer ("moved — canonical lives here: [link]") or deleted where possible, and the announcement names the one true home. Silent canonicalization loses to the first person who edits their bookmarked copy.
- The prevention is structural: the doc lives on a versioned platform (history replaces suffix-naming) · links, never attachments (an attachment is a fork) · the filename loses its version theater per filename-convention · and mid-negotiation external docs get one named copy-holder who alone sends/receives versions.
Output Format
Version Untangle: [document]
The Census
| Copy |
Location |
Modified |
Editor |
Signals |
The Verdict
[Canonical: which and the lineage why · divergence found: yes/no · if yes: the merge is the canonical]
The Merge (if diverged)
[Section-level reconciliation · judgment calls × confirming author · the audit-trail note for legal docs]
The Install
[The one home (versioned platform) · pointers placed over old copies · the announcement line · links-only norm + the external copy-holder rule if applicable]
Quality Checks
Anti-Patterns
1---2name: version-chaos-untangler3description: Untangle a document that exists in six copies across email, drives, and desktops — establish the canonical version defensibly, merge the divergent edits, and install the single-source rule that prevents the rematch. Use when asked which version is the real one, merge these document copies, we've been editing different files, or stop the version chaos on this doc. Produces the version census with the canonical verdict, the divergence merge plan, the announce-and-redirect step, and the single-source going-forward rules.4---5
6# Version Chaos Untangler Skill
7
8Six copies of the contract: email attachments, two drives, someone's desktop, one renamed `-final-JT-edits`. Two have diverged — different edits on a shared ancestor — and the team is now editing in parallel universes. Untangling is forensic then structural: census every copy (where, modified-when, by-whom), establish the canonical *defensibly* (newest is not automatically rightest), merge what diverged, then kill the conditions — one home, links-not-attachments, and platform version history doing what filename suffixes failed to do.
9
10## What This Skill Produces
11
12- **The version census** — every known copy: location, modified date, editor, size/diff signals
13- **The canonical verdict** — which version wins and *why* (the lineage argument, not just the timestamp)
14- **The merge plan** — the divergent edits reconciled, with the who-confirms list for judgment conflicts
15- **The single-source install** — one home, the redirect of every old copy, and the links-only norm
16
17## Required Inputs
18
19Ask for these if not provided:
20- **The copies** — everywhere it lives (search email attachments by filename, both drives, ask the usual suspects); the census is only as good as the hunt
21- **The stakes** — a contract mid-negotiation and a team doc carry different merge rigor; legal-adjacent docs get the careful version
22- **The editors** — who touched it recently; diverged edits need their authors for the judgment calls
23- **The platform reality** — where the canonical *should* live (the versioned platform — cloud doc or drive with history — not email, not desktops)
24
25## Framework: The Untangle Rules
26
271. **Census before choosing:** list every copy with modified-date and editor before any verdict — the loudest "mine is latest" claim is wrong often enough that the census is not optional. Email attachments are copies-at-a-timestamp, and every send forked the universe.
282. **Canonical is lineage, not timestamp:** the winner is the copy containing the most confirmed-wanted edits — usually but not always the newest. The tell for divergence: two copies both modified after their common ancestor. When found, neither is canonical yet; the *merge output* is.
293. **Merge by diff, confirm by author:** compare divergent copies section-by-section (platform compare tools where they exist); mechanical differences merge directly, judgment conflicts (two different edits to the same clause) go to their authors by name. The merge doc lists every judgment call and who confirmed it — for legal-adjacent docs, that list is the audit trail.
304. **Kill the old copies loudly:** every non-canonical copy gets replaced by a pointer ("moved — canonical lives here: [link]") or deleted where possible, and the announcement names the one true home. Silent canonicalization loses to the first person who edits their bookmarked copy.
315. **The prevention is structural:** the doc lives on a versioned platform (history replaces suffix-naming) · **links, never attachments** (an attachment is a fork) · the filename loses its version theater per [filename-convention](../filename-convention/SKILL.md) · and mid-negotiation external docs get one named copy-holder who alone sends/receives versions.
32
33## Output Format
34
35# Version Untangle: [document]
36
37## The Census
38| Copy | Location | Modified | Editor | Signals |
39|---|---|---|---|---|
40
41## The Verdict
42[Canonical: which and the lineage why · divergence found: yes/no · if yes: the merge is the canonical]
43
44## The Merge (if diverged)
45[Section-level reconciliation · judgment calls × confirming author · the audit-trail note for legal docs]
46
47## The Install
48[The one home (versioned platform) · pointers placed over old copies · the announcement line · links-only norm + the external copy-holder rule if applicable]
49
50## Quality Checks
51
52- [ ] Every findable copy is in the census before any verdict
53- [ ] The canonical argument is lineage-based, not timestamp-only
54- [ ] Divergent judgment calls were confirmed by their authors, listed
55- [ ] Every old copy now points to the canonical or is gone
56- [ ] The doc's new home has version history — the suffix era is over for this file
57
58## Anti-Patterns
59
60- [ ] Do not crown the newest by default — the newest fork of the wrong branch is still wrong
61- [ ] Do not merge judgment conflicts by taste — authors confirm their own clauses
62- [ ] Do not canonicalize silently — unannounced truth loses to bookmarked habit
63- [ ] Do not leave the winner on a desktop or in a thread — un-versioned homes restart the chaos
64- [ ] Do not send attachments of the untangled doc — every attachment is the sequel's opening scene
gabrielmoreira