Salesforce Field Audit

Salesforce field audit

When to use this

• Someone asks whether a field, or a set of fields, can be deleted.
• You are validating an existing field analysis (a spreadsheet of Keep/Review/Remove calls).
• An object is about to receive new automation and needs trimming first.
• An org-cleanup or technical-debt effort touches custom fields.

When not to use this: a single field you already know is referenced, or a brand-new object with no history. The overhead is not worth it below roughly ten fields unless the object is load-bearing.

The core principle

Population tells you how much data is in a field. It never tells you what depends on it.

These two answers agree on busy, obviously-live fields and diverge everywhere else — formula fields, transient state flags, integration keys, anything frozen years ago. Every serious error in this kind of analysis comes from substituting one for the other.

A field with 750,000 values can be dead. A field with zero values can be load-bearing.

The five checks

Someone who reads only this section is already better at the task.

1. Name the org and the object before you count anything. Same-named fields exist on multiple objects, so an unscoped count silently measures the wrong one. Equally: record which org each number came from. Sandboxes are routinely much thinner than production on specific fields — a field can read 0 in sandbox and hold thousands of rows in production. A number without its org and object attached is not evidence.

2. Measure flow, not just stock. MAX(field), count of future-dated values, and CreatedBy on recent writes. Three cheap queries. Population is a stock measure and cannot tell you a process stopped five years ago.

3. A formula field has no meaningful population figure. If the formula references $User, $UserRole, $Profile or TODAY(), the percentage measures who ran the query. If it returns IF(...,1,0) or CASESAFEID(Id), it can never be null and the percentage measures arithmetic. Read the formula body; skip the count.

4. Trace one hop forward, and record the role rather than the count. What consumes this field — a flow entry criterion, a formula, a roll-up on the parent object, a validation rule, a related list, a dashboard grouping? Then, inside each report: sole filter, date axis, grouping, non-blank row gate, or display column. Write down what that consumer would do if the field vanished.

5. A Review is unfinished until it names the exact question and the person who answers it. Otherwise it is indistinguishable from an unanswered field, and it will still be there next year.

The three failure modes that actually bite

A deleted filter fails open. Deleting a field used as a report or list-view filter does not empty the report. It silently widens it. Nothing looks broken, so nobody reports it. This is strictly more dangerous than deleting a display column, and it is why check 4 records role rather than count.

Tool zeros are not evidence of zero. Metadata knowledge bases miss things structurally. Four such gaps were live in sf-intelligence itself until 0.3.0, and each produced a confident safe on a field the platform refuses to delete:

• Roll-up coupling held as a node property, never an edge — so an incoming-edge walk from the child field never reached the roll-up declared on the parent.
• Condition field references held as a property, never edges — so a field used only in a flow entry criterion, a workflow-rule criterion or a validation-rule condition read "layout only". Flow ships two XML spellings of the same condition triplet (<leftValueReference> in <decisions>, <field> in <start><filters>); reading only the first made every record-trigger entry criterion parse to nothing.
• Formula __r traversals skipped, so a field read only via Parent__r.Field__c showed zero referrers.
• FlexiPage relatedListFieldAliases unparsed, so a field rendered twice on a record page had zero referencers.

All four are closed in 0.3.0. A fifth gap of the same family — the usage-ranked report cap — is still open and is yours to handle in the runbook (see below); it is disclosed rather than fixed.

The dangerous property the four closed ones shared: all sat inside metadata families the tool had fully retrieved, so no coverage caveat fired and the verdict presented as clean. A tool can only warn you about gaps it knows it has. Before recording "no references", run your method against a field you know is referenced and confirm it can see anything at all — the positive control is what tells you which kind of zero you are holding. The closures narrow the gap; they do not remove the need for the control.

Undocumented reference grammars. Field references appear in several distinct textual forms per metadata type, and orgs use forms the documentation doesn't mention. Derive the grammar empirically (see below) instead of assuming it. A search using an incomplete grammar returns zero and certifies a live field as safe.

Deriving the reference grammar (do this before any searching)

Never assume how a field is referenced in metadata. Establish it:

1. Pick a field you are certain is referenced (one on a page layout, say).
2. Grep the whole metadata tree for its API name.
3. Read the actual matched lines in each metadata type and record every distinct form.
4. Only then build your search patterns.

Expect multiple forms per type. Reports alone commonly use direct Object.Field, child-relationship Relationship__r$Field, foreign-key-prefixed variants, and object-prefixed variants — and references live in several XML tags, not only <field>. Getting this wrong is the single highest-consequence mistake in the audit, because it produces confident false negatives.

Two sources of truth, complementary blind spots

Use both. Neither is sufficient:

• A complete local metadata retrieval (grep-able). Covers report/dashboard/workflow surfaces that knowledge bases often mark partial. Misses dependency edges and semantic relationships.
• A metadata knowledge base or dependency graph. Covers edges grep cannot compute. Has structural blind spots (see above) and declared coverage gaps.

When they disagree, report both and say which you trust and why. Do not silently pick one.

Where this sits among the sfi skills

This skill owns the decision: whether a field can be deleted, and what must happen first. It composes the other skills rather than replacing them.

Before Phase 0, raise the report cap. The default refresh pulls the top SFI_REPORTS_CAP (500) reports and dashboards by usage. On an org with thousands, a field's report count is drawn from a fraction of the corpus — and report counts are evidence this audit leans on hard:

SFI_REPORTS_CAP=10000 sfi refresh --no-pull    # recompute from existing source

Then confirm with sfi.coverage_report that Report/Dashboard reads complete rather than pending. A pending coverage under a "no reports use it" verdict is a Phase 0 failure, not a Phase 4 limit.

The workflow

Five phases. Full operating procedure with commands in references/workflow.md.

Verdict taxonomy — four values, not three

The fourth value is what makes the output actionable. Without it, everything that isn't obviously safe collapses into "Review" and nothing moves.

Also distinguish three severities of dependency, because they are not the same problem:

• Blocking — the platform refuses the delete (flow references, formula sources, roll-up fields, validation-rule bindings, master-detail)
• Breaking — the delete succeeds and something silently misbehaves (filters, sort fields, related-list keys, dashboard groupings)
• Cosmetic — cleanup only (layout placement, report-type columns, field-level security)

Running it with agents

This audit is a natural fan-out: the per-field work is embarrassingly parallel, and the adversarial pass requires independent agents that cannot see each other's reasoning. The reference run used 60 agents across four phases and reverted a third of its own corrections in the process.

Do not parallelise Phase 0. The scout output is the shared evidence base; agents deriving it independently diverge, and every downstream comparison is silently invalidated.

references/orchestration.md has the runnable machinery: phase-by-phase agent counts, the shared prompt block, JSON schemas for verdicts and refutations, the three-lens adversarial pattern with majority vote, the scouting shell commands, and the knowledge-base tool inventory with its observed blind spots.

Detailed references

Load these as needed — do not read all of them up front.

• references/orchestration.md — agent invocation, prompt architecture, output schemas, adversarial voting, tool inventory and blind spots.
• references/workflow.md — the phase-by-phase operating procedure, with the shell techniques for grammar derivation, collision mapping, evidence indexing, and fan-out.
• references/checklist.md — the exhaustive per-field checklist, by surface category, with how to interpret a hit versus a miss. Work through this mechanically.
• references/traps.md — the trap catalogue: every way this analysis goes wrong, with symptom, worked example, and the check that catches it.
• references/reporting.md — epistemic discipline, coverage caveats, and the output contract.

Quick reference

Before recording any disposition, answer:

1. Which org did this number come from, and which object was named in the query?
2. Is this a formula field? (If yes, population is meaningless — read the body.)
3. What is the newest value, and are any values future-dated?
4. Name one thing that consumes this field. What would it do if the field vanished?
5. In each report that uses it: filter, date axis, grouping, row gate, or display column?
6. Have I confirmed my search method can find a reference I know exists?
7. If this is a Review — what exactly is the question, and who answers it?

Blind spots no static analysis closes. State these explicitly rather than implying full coverage:

• Dynamically-built SOQL and reflective field access (.get('Field__c'))
• Field lists stored as org data in custom settings or custom metadata and read at runtime — invisible to both metadata retrieval and knowledge base, and they fail at runtime rather than at deploy
• External ETL and integration job definitions living outside the platform
• Managed-package internals
• Private report folders, and report/dashboard filters as distinct from columns
• Email template merge fields
• Field history rows, which a delete destroys permanently and no export of current values recovers

Always separate "checked and found nothing" from "could not check." They look identical in a report and mean opposite things.