AI Visibility Codebook Migration Impact Checker

The short answerA codebook revision can move an AI visibility score even when no answer changed. Freeze the old and new versions, preserve the original labels, auto-map only declared equivalent renames or merges, and route splits, retirements, boundary changes, and missing rules to human re-review.

Impact analysis is not semantic approvalThis checker applies the migration rules you supply. It cannot prove that two definitions mean the same thing, decide a new label from answer evidence, or make a pre-change and post-change series comparable.

Treat a codebook edit as a measurement change

Preserve the source recordKeep every original label, observation ID, prompt, engine, timestamp, and period. A migration output is a new ledger, never a silent overwrite.

Map only declared equivalentsAn unchanged label or a frozen rename or merge may receive a proposed label when the rule explicitly says no re-review is required.

Queue changed meaningSplits, retirements, changed boundaries, missing mappings, and any rule marked for review remain unresolved until evidence is reviewed under the new codebook.

Browser-local migration control

Measure the revision before changing a report

Paste UTF-8 CSV. Nothing leaves this tab. The checker accepts at most 5,000 observation rows and 250 migration rules.

01 · Migration identity

Freeze the versions and decision owner

These fields identify the generated ledger and memo. They do not verify an external codebook file or a person’s authority.

Project or dataset name

Organization

Prior codebook version

Revised codebook version

Revision effective timestampUse ISO 8601 with Z or a numeric UTC offset.

Migration decision owner

Source observations retainedThe original input and prior codebook remain unchanged outside this page. Migration map frozenEvery rule below was approved before this impact run and will be versioned if changed. No silent trend bridgeReports will show the version boundary unless a separate comparability analysis supports a bridge. Review queue remains unresolvedQueued rows will not inherit a final label from this structural check.

02 · Historical observations

Paste the source label ledger

Header order is exact. IDs must be unique; labels and identifiers are case-sensitive after surrounding whitespace is removed.

Observation CSVExact header: observation_id,prompt_id,engine,observed_at,period,current_label

03 · Frozen migration map

Declare one rule per prior label

Allowed change types are unchanged, rename, merge, split, retire, and boundary_change. Review flags are yes or no.

Migration-rule CSVExact header: old_label,new_label,change_type,requires_review,change_note

Local processing boundary. The page hashes the normalized CSV used for analysis and creates new downloads. It does not read files, call an API, save browser storage, or mutate the pasted source.

04 · Run and retain

Create the impact ledger and review queue

Use a worked example to inspect the exact behavior. Formula-like cells receive a disclosed leading tab only in downloadable CSV fields.

Complete the identity record and paste both CSV inputs.

Migration analysis ready

Candidate ledger generated

Observations—

Unchanged—

Deterministic candidates—

Human re-review—

Unmapped blockers—

Normalized observation CSV SHA-256—

Normalized migration map SHA-256—

Impact ledger SHA-256—

Manual review queue SHA-256—

Migration memo SHA-256—

Formula-risk cells defended—

Release blockers

Completed checks

Impact preview

First eight rows only. The downloadable ledger contains every source row and never replaces original_label.

First eight codebook migration impact rows
Observation	Prompt	Engine	Observed at	Period	Original label	Proposed label	Disposition	Change type	Rule note

Migration impact memo

Exact input and output contracts

Headers are case-sensitive and must appear once in the documented order. CSV quoting follows RFC 4180-style double-quote escaping.

Codebook migration input and output schemas
Artifact	Exact fields	Gate
Historical observations	`observation_id, prompt_id, engine, observed_at, period, current_label`	Unique nonblank observation IDs; valid offset timestamps; no blank source fields; at most 5,000 data rows.
Migration rules	`old_label, new_label, change_type, requires_review, change_note`	One rule and a nonblank rationale per old label. Splits, retirements, and boundary changes must require review. Rename and merge need a new label.
Impact ledger	All source fields plus `original_label, proposed_label, migration_disposition, change_type, requires_review, change_note`	Original label is copied, never overwritten. Unmapped labels remain blocked rather than inferred.
Manual review queue	Impact-ledger fields for `human_re_review` dispositions only	No final revised label is produced by this page for queued rows.

Method and limits

Parse both CSV inputs, require the exact headers, normalize line endings, and reject malformed quotes, duplicate IDs, duplicate rule labels, blank required cells, invalid timestamps, unsupported change types, and unsupported review flags.
Validate migration semantics structurally. unchanged must keep the same label and cannot require review. rename or merge needs a destination label. split, retire, and boundary_change must require human re-review.
Join each historical label to one frozen rule. Unchanged rows retain the same proposed label. Renames and merges marked no become deterministic candidates. Every other mapped row enters the manual queue. Missing rules block a release-ready ledger.
Hash the normalized inputs and exact output bytes with SHA-256. Export an append-only-style impact ledger, a separate review queue, and a memo that states the evidence boundary.

Important boundary. Structural validity is not semantic validity. This page does not compare codebook prose, inspect answer evidence, choose a label, estimate agreement, re-score a report, prove historical comparability, approve a baseline bridge, or establish compliance. A deterministic candidate is still a proposed migration created from the user-supplied rule.

Sources and operating context

IAB, Measuring Visibility in the AI Era — measurement stability, reproducibility, and disclosure context.
Unitlab, Changing Ontologies Safely — impact analysis, preserve/transform/re-annotate choices, and semantic compatibility.
Potato Annotation codebook documentation — revision stamps, stale-instance worklists, and retroactive curation history.
SearchScore scorer changelog — a concrete AI visibility example of versioned scoring changes and baseline breaks.

Sources retrieved August 24, 2026. External methods inform the operating context; this page’s exact rules are the disclosed local implementation above.

Frequently asked questions

What does the codebook migration impact checker do?

It joins historical AI visibility labels to a frozen migration map, preserves every original label, identifies deterministic relabel candidates, and creates a separate queue for observations requiring human re-review.

Which codebook changes can be mapped without re-review?

Only an unchanged label or a predeclared rename or merge with requires_review set to no is treated as deterministic. Splits, retirements, boundary changes, and rules marked for review stay unresolved.

Does the checker rewrite my historical data?

No. Pasted data stays in the browser, source rows are not edited, and every output keeps the original label beside a proposed label and disposition.

Does a deterministic mapping prove the new label is correct?

No. The tool checks structure and applies the mapping supplied by the user. It cannot validate whether two codebook definitions are semantically equivalent or whether a migration decision is methodologically appropriate.

Should pre-change and post-change scores share one trend line?

Not automatically. A material coding-rule change can break comparability. Preserve the old version, document the boundary, re-review affected history when justified, and open a new baseline unless a defensible bridge has been established.

Where is the pasted observation data sent?

Nowhere by this page. Parsing, validation, hashing, mapping, preview, and downloads happen locally in the current browser tab; reloading clears the data and results.

Need a defensible version boundary?

Keep the historical record—and make the new method inspectable.

Quoted First can review the codebook delta, re-review design, baseline boundary, and disclosure packet before revised scores reach a decision.

Review the migration protocol