Sf Records

Salesforce Record Stewardship

Data steward for a single object at a time. Answer two questions and nothing else: what is wrong with the records on this object, and how do I safely fix it? Profiling is free; every write is proposed, batched, verified, and reversible.

This skill does not own query syntax (sf-data does), web research (sf-leads does), or org-wide scoring (sf-audit does). It owns the records.

Dispatch

Always name the object explicitly in the first line of output. A stewardship run that silently drifted from Account to Contact is a run nobody can audit.

Execution modes

See references/execution-modes.md (tool-name mapping preamble and the headless rule). Initialize the connection first (org_init convention).

Headless = propose-only. In non-interactive runs, Inspect runs fully; Fix and Bulk stop at the proposal table; Dedupe stops at the candidate list. Merges never execute headless under any caller-granted permission — a merge cannot be undone by rerunning the skill.

Phase 0 — Describe first, always

Never assume a field exists. Before any query, sobject_describe the target object and work from what the org actually has:

1. Confirm the object. Custom objects, namespaced objects, and objects renamed in the UI all resolve differently — match on API name.

2. Inventory the fields that matter for the workflow: type, length, nillable, updateable, defaultedOnCreate, picklistValues[].active, calculated (formula fields cannot be written), and unique/external-id flags (they are your best dedupe keys). If the connector's describe tool returns a thin field list (some return only name/label/type/updateable), recover the rest from the Tooling API rather than assuming — SELECT QualifiedApiName, DataType, Length, IsCompound, IsNillable, IsCalculated FROM FieldDefinition WHERE EntityDefinition.QualifiedApiName = 'Account' — and see references/execution-modes.md for the connector variation and the compound-address blind spot.

3. Find custom fields shadowing standard ones. Orgs routinely keep the real value somewhere else: Contract_Value__c beside a stale Amount, Industry_Segment__c instead of Industry, a custom Primary_Email__c beside Email. Describe alone never proves shadowing — populated-rate sampling does. Take the total once and a populated count per candidate field —

   SELECT COUNT() FROM Opportunity
   SELECT COUNT() FROM Opportunity WHERE Amount != null
   SELECT COUNT() FROM Opportunity WHERE Contract_Value__c != null
   

   — one query per field, because COUNT(Field) is rejected outright on textarea, long text area, boolean, and encrypted fields, while COUNT() with a != null filter works on every filterable type. Add a recency comparison, and when a shadow candidate wins on population, ask which field is authoritative before proposing any write to either. Managed packages (CPQ, billing, subscription apps) frequently own the real value and recompute anything you write into their field.

4. Note the automation surface: active validation rules, required fields per record type, and duplicate rules. They decide which of your proposed fixes will actually land.

5. Inventory the code automation on the object — Apex triggers and record-triggered flows, including managed-package ones — before proposing any write. A managed trigger can mirror or overwrite your fix (address-sync packages copy billing into shipping), so finding it now is the difference between an honest proposal and a surprise:

   SELECT Id, Name, Status, NamespacePrefix FROM ApexTrigger WHERE TableEnumOrId = 'Account'
   

   (Tooling API; pair it with FlowDefinition / FlowDefinitionView for active record-triggered flows on the same object.)

Record the describe findings once and reuse them across the run.

Data-quality canon

The universal record-writing rules — active picklists, address/code conventions, field lengths, anti-fabrication, source attribution, email verification and opt-out/bounce one-way doors, departed people, and write discipline — are shared canon at ../../shared/standards/record-data-quality.md. Read it before the first write of any run and cite it by section (§1–§8) instead of restating it.

Three canon rules are load-bearing here and get named explicitly in output: §4 (blank beats invented), §6 (opt-out and bounce flags are one-way doors — never cleared as a side effect of a bulk update), and §8 (propose, batch, verify, never overwrite non-null without instruction).

Inspect — profile an object's data health

Read-only. Produces the map the other three workflows navigate by.

1. Volume and shape. SELECT COUNT() FROM {Object}, plus counts by the object's primary segmentation field (RecordType, Stage, Status, Type) and by CreatedDate year. Volume decides whether later phases can query directly or must chunk.
2. Completeness per field. For the fields the playbook flags as mattering, take the total once (SELECT COUNT() FROM {Object}) and one populated count per field (SELECT COUNT() FROM {Object} WHERE {Field} != null). Use a single grouped COUNT(Field) query only where every field in it is an aggregatable type — COUNT(Field) is invalid on textarea, long text area, boolean, and encrypted fields, which is exactly what the *_Notes__c / *_Flag__c shadows tend to be, so the COUNT() + null filter is the portable form. Report as a rate, not a raw number — "BillingCountry populated on 41% of 12,400 accounts" is actionable; "5,084" is trivia.
3. Validity. Picklist values present in data but no longer active (canon §1 — GROUP BY the data, diff against the describe's active list; the authoritative check is the UI API picklist-values endpoint via a generic REST tool, and when the connector has neither that nor a full describe, report picklist validity as unverified rather than trusting the GROUP BY — see references/execution-modes.md); country/state codes that violate the org's dominant convention (§2); emails failing a shape check; numbers and dates outside plausible ranges.
4. Consistency. Cross-field contradictions from the object playbook — a closed stage with a future close date, a contact with no account, a parent pointing at itself.
5. Ownership and staleness. Missing owners, inactive owners (Owner.IsActive = false), and owners that are not real people — integration, system, and Automated Process users are IsActive = true and pass an inactive-owner check while leaving nobody accountable for the record. Exclude them from the "owned" count and flag them as their own finding; the same applies to queue ownership where the object allows it. Then records untouched past the object's natural clock (LastModifiedDate, LastActivityDate).
6. Duplicate pressure. A cheap aggregate on the object's natural key — count of keys appearing more than once. Not the full Dedupe run; just the size of the problem.

Per-object specifics — which fields, which contradictions, which traps — are in references/object-playbooks.md. Report shape:

## Data health: {Object}   ({record count}, {UTC timestamp})

| Finding | Severity | Records | Rate | Fix path |
| ... one row per finding, severity-ranked ...

## Top 5 fixes by value
<what to fix first, why, and which workflow does it>

Severity: CRITICAL = breaks a business process or a downstream system (orphaned records, cycles, missing required linkage). HIGH = wrong data that people act on (retired picklist values, invalid amounts, duplicates on a key). MEDIUM = missing data that limits reporting. LOW = cosmetic or convention drift.

Dedupe — find duplicates and plan merges

Detection is safe; merging is not. These are separate steps with a user between them.

Matching strategy, in strength order (details and per-object keys in references/dedupe-strategies.md):

Between tiers 2 and 3 sits a signal worth naming: one registrable domain, several different normalized names. That is usually subsidiaries, not copies — the default recommendation is an account hierarchy, not a merge (references/dedupe-strategies.md, When not to merge at all).

Normalize before comparing, never after: lowercase, trim, strip punctuation, legal suffixes (Inc/LLC/Ltd/GmbH/Corp) and trailing geography or division qualifiers, reduce websites to registrable domain, strip +tags from emails. Report the normalization rules used — a dedupe whose matching rules aren't stated can't be trusted or repeated.

Do NOT auto-merge, ever:

• Records in different record types, currencies, or business units.
• Records with different owners in a territory-managed org until the owner question is answered.
• Records where each side has non-null values in the same field that disagree — that is a data decision, not a match decision.
• Accounts with children (contacts, opportunities, cases, hierarchy children) until the reparenting consequences are shown.
• Anything matched only at tier 3.
• Person Accounts, or Contacts under different Accounts (Salesforce forbids or complicates both).

Merge is a Salesforce operation with real consequences. The losing record is deleted, its child records reparent to the winner, field values from the loser fill only the winner's blank fields unless overridden, and audit history from the losing record does not survive intact. Merges are always user-confirmed, one group at a time or in an explicitly approved list, and never headless. Before each merge, present:

| Field | Winner (Id) | Loser (Id) | Result after merge |

plus the child-record counts that will reparent, and the master-record choice with its reason (oldest, most complete, most activity, the one integrations reference). Ask before executing. After merging, verify the winner and its reparented children.

When the org has Duplicate Rules and Matching Rules configured, say so and prefer them — reporting DuplicateRecordSet/DuplicateRecordItem findings is better stewardship than inventing a parallel matching scheme.

Fix — propose and apply corrections

The default workflow for "clean up my X". Never a single sweeping update.

1. Scope the fix to one finding from Inspect (or the user's own criteria). One finding per Fix run keeps the proposal reviewable.

2. Gather evidence from inside the org: the parent record, a sibling field, the org's dominant convention, an existing related record. There is no web research here — that is sf-leads.

3. Propose. Always this table, never prose:

   Record (Id / Name)	Field	Current	Proposed	Evidence

   With a count, the batch plan, and any records deliberately excluded and why. Values that would overwrite a non-null field are listed separately and are off by default — they only proceed on an explicit instruction naming that overwrite.

4. Apply in batches of ≤200 records (the user may raise it; say what you raised it to and why). Stop on the first batch that errors, report the error and the partial state, and do not continue automatically.

5. Verify after write. Re-query the affected records and compare against the proposal. Automation can accept a write (HTTP 204) and revert it — when a value reverts, automation owns that field. Report which fields reverted, don't retry them, and hand the automation question to sf-flow or sf-apex (canon §8).

6. Report applied / reverted / failed / skipped with counts.

Bulk — safe mass updates

For deliberate, large, uniform changes: owner reassignment, status transitions, backfilling a new field, applying a convention.

1. Dry-run counts first. Run the selection as COUNT(Id) before selecting rows, and show the user the number and the exact criteria. If the count differs materially from what the user expected, stop and reconcile — a mass update on a wrong filter is the single most expensive mistake in this skill's territory.
2. Rollback plan before the first write. Query and preserve Id plus the prior value of every field being changed, and keep it where the user can reach it (a file in code-execution modes; an in-context table capped to a reviewable size otherwise). State plainly what rollback restores (field values) and what it cannot (deletions, merges, fired automation, sent emails, downstream integration events).
3. Chunk. ≤200 records per call; sequence chunks and log which chunk ranges succeeded so a partial failure is resumable rather than re-runnable from zero.
4. Guardrail-hook awareness. The plugin's PreToolUse guardrails flag broad destructive DML and high-risk permission payloads and can turn a write into an explicit confirmation prompt. Expect it, don't work around it, and never restructure a call purely to slip under a threshold — if a guardrail fires, that is the moment to re-confirm scope with the user.
5. Never mass-update opt-out, bounce, or consent fields (canon §6); audit/system fields; or fields owned by a managed package, without a named, explicit instruction for that specific field.
6. Verify a sample of at least 20 records (or all, if fewer) after each chunk, and the full set at the end.

Deletion is not a Bulk operation in this skill. Stale records get flagged and dated (canon §7); when the user genuinely wants deletion, hand off to sf-data with the scoped Id list and the rollback caveat stated.

Pitfalls

Cross-skill handoffs

• Query syntax, selectivity, DML execution mechanics, deletions → sf-data
• Filling gaps from web research (titles, industries, company data) → sf-leads
• Campaign and member performance analysis → sf-campaigns
• Org-wide quality scoring and client-ready audit documents → sf-audit (also its report-template.md §7–8 when the user wants a document)
• The automation that reverts your writes → sf-flow / sf-apex
• Missing fields, picklist values, or duplicate rules that the data needs → sf-metadata (a metadata change, not a record update)

References