Field Rename Verification

Wrong skill? General code modification → blast-radius-check. Pre-commit checks → pre-commit-gate. Completion verification → verification-before-completion.

When to Use

• Renaming a field, column, or property across one or more services
• Changing an API contract (request/response shape, query parameters, headers)
• Refactoring a data model that crosses service boundaries
• Splitting or merging fields (e.g., trackingLine → inboundLine/outboundLine)

Why Renames Are Dangerous

Field renames and API contract changes are the #1 source of production incidents from "complete" work that wasn't actually complete.

Core principle: Trace the FULL data flow, not just the obvious touchpoints.

Incident that created this skill: PROJ-XXX (Feb 2026) - Renamed trackingLine to inboundLine/outboundLine across 6 PRs, but missed the telephony client adapter that actually calls voice-service. Quality gates (lint, typecheck, tests) all passed because each service was internally consistent.

The Iron Law

NO FIELD RENAME IS COMPLETE UNTIL YOU VERIFY EVERY PATH:
READ → STORE → PASS TO OTHER SERVICES

If you only traced READ and STORE, you missed PASS.

The Three Paths

Every field has THREE data flow paths that must be traced:

The PROJ-XXX mistake: Traced READ (settings-service → post-lead.ts) and STORE (lead table), but missed PASS (telephony-client.adapter → voice-service).

Pre-Rename Checklist

BEFORE claiming a field rename is complete:

1. Grep Exhaustively

# Search ALL affected repos for the old field name
grep -rn "oldFieldName" --include="*.ts" --include="*.tsx" --include="*.js" repo1/ repo2/ repo3/

# Also search for the CamelCase, snake_case, and UPPER_CASE variants
grep -rn "old_field_name\|OLD_FIELD_NAME\|OldFieldName" --include="*.ts" repo/

2. Trace Every Service Boundary

For each service that handles this field:

3. Verify Type Definitions

# Check if old types are still published
grep -rn "oldFieldName" node_modules/@yourorg/*/dist/*.d.ts

If old types exist in node_modules, consumers may compile against wrong contract.

4. Integration Test the Full Path

Unit tests pass but integration fails because:

• Service A sends oldFieldName
• Service B expects newFieldName
• Both services' unit tests pass (internally consistent)
• E2E test fails (contract mismatch)

REQUIRED: Run at least one test that crosses the service boundary you changed.

Common Failure Patterns

Service Boundary Verification

For cross-service field renames, verify at BOTH ends:

Service A (sender)        Service B (receiver)
─────────────────         ────────────────────
HTTP client sends    →    Route handler expects
message.fieldName         body.fieldName
     ↓                         ↓
   MUST                      MUST
   MATCH                     MATCH

Worked failure (PROJ-XXX):

• service-b (receiver) expected inboundLine/outboundLine ✅
• service-a (sender) still sent legacyLine ❌

Red Flags - STOP

If you find yourself thinking:

• "The database column uses the old name, that's fine" → Maybe, but verify callers
• "I just need to update the schema" → No, trace the full flow
• "The tests pass so it's done" → Tests may not cross the boundary
• "I updated the obvious files" → The non-obvious ones break production
• "It's just a field rename" → Field renames touch everything

The Gate Function

BEFORE claiming a field rename is complete:

1. GREP: Run exhaustive search for old field name in ALL affected repos
2. LIST: Enumerate every service boundary the field crosses
3. TRACE: For each boundary, verify BOTH sender and receiver
4. TEST: Run at least one integration test crossing each boundary
5. ONLY THEN: Claim the rename is complete

Skip any step = incomplete work

Companion Skills

• verification-before-completion — General verification discipline
• systematic-debugging — When the field mismatch causes runtime errors
• link-verification — For verifying API endpoint URLs still exist

Failure Modes