--- name: music_release_metadata_reconciliation description: Reconcile a music release package before distributor delivery: track order and titles, ISRCs, UPC, contributor and split records, territory and release flags, cover and audio asset references, and credits, checked across the distributor form, the files on disk, and the split sheets. Use when an album, EP, or single is about to be uploaded, moved between distributors, or fixed after a metadata rejection. --- # Music Release Metadata Reconciliation ## Purpose Stop a release at the last point where mistakes are cheap. Once a distributor sends the package to stores, the form data becomes the store record, and fields such as ISRC and UPC are hard or impossible to edit in place on a live release. This skill compares three sources that should agree and often do not: what was typed into the distributor form, what files are actually in the package, and what the split sheets say was agreed. It ships a reconciliation script that lists mismatches as blockers, a field map, a split and credit check sheet, and a worked album delivery that fails, gets fixed, and passes on recheck. ## Workflow 1. Freeze the three sources. Export or copy the distributor form values into `release.json` and `tracks.csv`, copy the split sheets into `splits.csv`, and put the audio files and cover in the same folder. Work from copies. If the form changes after this point, re-export and rerun, because a check against a stale export proves nothing. 2. Build the three input files using the formats in `references/field-map.md` and the examples. `release.json` holds release title, primary artist, UPC, cover file, cover parental advisory flag, release date, and territories. `tracks.csv` holds one row per track: track_no, title, version, isrc, primary_artist, featured_artists, explicit, audio_file, duration_sec. `splits.csv` holds one row per writer per track: track_title, writer_legal_name, role, share_percent, pro, ipi, publisher. 3. Run the script before any upload. `python3 scripts/reconcile.py ` Add `--json` for a machine readable report. Exit code 1 means blockers exist. Read every line, including warnings. A warning is a deliberate choice you can explain, or it is a blocker you have not admitted yet. 4. Fix blockers at the source that is wrong, not at the source that is easiest to edit. Work through the classes the script and the field map cover: - Track order and titles: form order is the running order stores show. Numbers must run 1 to N with no gaps. Titles must match character for character across form, split sheet, and ISRC record, with version wording in the version field. - ISRCs: 12 characters, 2 letters, 3 alphanumeric prefix characters, 2 digit year of reference, 5 digit designation. No duplicates, no reuse on a different recording. Reuse the existing code when the same recording moves distributor. Assign a new code when the recording itself changes, for example a remix, an edit, or a clean version. - UPC or EAN: 12 digits for UPC-A or 13 for EAN-13, and the last digit must pass the GS1 Mod-10 check digit test the script runs. Keep the column as text in spreadsheets so a leading zero survives. - Splits and credits: one split sheet per track, legal writer names, composition shares total 100 per track. Master shares, if tracked, total 100 on their own side and never get mixed into the composition total. Producer, engineer, and featured performer credits go in contributor fields, not inside title text. - Territory and release flags: territories are WW or a list of 2 letter codes with no repeats. A licence, sample, or featured artist deal that is limited by country must appear as an explicit list. Explicit is a per track flag set from the lyric sheet. - Cover and audio references: every audio file named in the form exists in the package and is the final master, lossless where the distributor requires it. The cover file exists, is JPG or PNG, is square, and meets the distributor size rule, commonly 3000 by 3000 pixels in RGB. Any text on the cover matches the release title and artist exactly. A Parental Advisory logo on the cover with no explicit track is a blocker. 5. Do the hand checks the script cannot do. Walk `references/split-and-credit-check-sheet.md` once per track, filled from the split sheet rather than the form. Check cover text against metadata by eye. Check each track duration against the mastering log or ISRC reference record, since a shifted duration usually means the wrong edit was attached. Confirm the release date leaves the distributor its review window and matches the release plan. 6. Fix, re-export, and rerun until the script reports CLEAR and the check sheets are complete. In the worked example, `examples/broken/` reports 12 blockers: a bad UPC check digit, a duplicated territory and a spelled out territory, splits totalling 90, a duplicated ISRC, a malformed ISRC, a missing audio file, a gap in track numbers, a split sheet title that matches no track, a non square cover, and a Parental Advisory cover with no explicit track. `examples/fixed/` is the same album corrected, and reports CLEAR with no warnings. Run both to see the expected output before trusting the script on a real package. 7. Record the verdict and upload only after it. Save the final script output with the package, note who fixed each blocker and where the signed split sheets live, and only then submit in the distributor form. If a field had to change in the form, that change, not the local copy, is what gets rechecked on the next release from the same catalog. ## Output Contract Every reconciliation leaves: - The three input files as checked, `release.json`, `tracks.csv`, and `splits.csv`, matching the values actually submitted - The script report, with blocker and warning counts and a CLEAR or STOP verdict - One filled split and credit check sheet per track, from `references/split-and-credit-check-sheet.md` - A fix log: each blocker, which source was wrong, and what was changed - A statement of what was not checked, for example embedded file metadata or sample clearance, if those were out of scope for this pass ## Operating Rules 1. Quality beats the release date. A wrong ISRC, a short split total, or a missing audio file does not ship because a date was announced. 2. Never invent an identifier. If an ISRC or UPC is missing, record that the distributor will assign one, or get one from the proper manager or agency. A made up code that passes the format test still points royalties at the wrong place or at nowhere. 3. The split sheet is the agreement, the form is a copy of it. When they disagree on shares or names, the assented split sheet wins and the form gets corrected, unless the team signs a new sheet. 4. Composition and master are two different rights. Keep their shares, owners, and totals separate in every file and conversation. 5. Treat warnings as decisions. Missing IPI numbers, an MP3 master, or a small cover may be acceptable for a given distributor, but the package must say who accepted it and why. 6. Do not fix a live release by re-uploading the same tracks under new ISRCs. That splits stream counts and royalty history. Use the distributor metadata update path and keep the original codes. 7. Verify factual claims about a distributor or store rule against that distributor or store current help pages before acting on them. Specs in this skill, including the 3000 by 3000 cover rule, are common working standards, and a specific distributor limit overrides them.