Architect Impact Analysis

Architect impact analysis

Usage vs impact (§C3 contract)

Route by VERB. Impact ("what BREAKS if I change/delete X") is get_impact (this skill). Usage ("where is X USED / what references / depends on X") is sfi.find_component_usages (any type), or a family specialist (find_field_anywhere, find_code_usages, layout_assignments). Describe (what is / list / values) uses describe tools. Cite evidence tiers (graph edge confidence + grep text-match); an empty usage result is "no static evidence in the vault", NEVER "nothing uses this".

Overview

sfi.get_impact is the architect persona's headline tool: given a componentId, it walks the org graph one to three hops along incoming edges and returns every node that depends on the target, plus the edges connecting them. This skill teaches Claude how to drive that tool, organize the result for human reading, and — most importantly — disclose what the impact graph does not see, so the architect doesn't mistake a clean impact report for a clean impact reality.

The graph records roughly two dozen edge types across three confidence levels. declared edges come straight from Salesforce metadata (parentOf, usedInLayout, grantedBy, lookupTo, triggersOn for Apex triggers). parsed edges come from the formula tokenizer (validation rules, formula fields), the Flow XML walker (readsFrom, writesTo, triggersOn, callsApex), and the parser-grade Apex pass that runs by default (readsFrom/writesTo on fields, callsApex between classes, field-level SOQL reads). heuristic edges come from the regex/token Apex recall scanner (backfill for parse failures) and the frontend (LWC / Aura / Visualforce) scanner — supplemental Apex field reads/writes, and frontend references — and they do enter the impact graph. The boundary that matters for architects: Apex edges blend parsed (compiler-backed) and heuristic (pattern-recognized) tiers; dynamic SOQL/SOSL strings, reflective field access (get() / put()), and cross-method dataflow remain invisible. Apex method bodies are parsed and scanned — cite the per-edge confidence tier, and treat a thin Apex result as a coverage signal rather than proof of no dependents.

sfi.get_impact carries a soundness envelope (complete / blindSpots[] / staticCoverage) with two blind-spot kinds: dynamic-apex (an impacted class uses dynamic SOQL / reflective describe / Type.forName / untyped JSON — named by id) and, on a CustomField / CustomObject root, unwalked-referrer-class — the referrer classes that are NOT modeled as incoming edges and so were never walked: roll-up source coupling, layout placement, Flow decision/filter reads, and tab/app membership. That one is STRUCTURAL, so it names no ids; referrerClasses names the classes instead. Surface both — a complete: false impact result is a floor, not a ceiling, and on a field root "no referrers found" is "these classes were not checked", never a proven "nothing references this".

When to fire

Fire on impact-analysis phrasing. Concrete triggers:

• "What breaks if I…" — "what breaks if I change Account.Industry__c?", "what breaks if I delete this validation rule?", "what breaks if I rename OpportunityService?".
• "What depends on…" — "what depends on CustomField:Contact.Tier__c?", "what depends on this flow?".
• "What's the impact of…" — "what's the impact of removing this field?", "what's the impact radius of Account.Region__c?", "blast radius of this trigger?".
• "What touches / references / uses…" — "which components touch Industry__c?", "show me everything that references this field", "what uses MyClass?", "where is this field used?".
• "Is it safe to deprecate…" — "is it safe to deprecate Old_Status__c?", "can I retire this Apex class?", "can I remove this layout safely?".
• Formula-specific phrasing — "find formulas using Account.Tier__c", "which formula fields reference this?", "show me every formula that touches this field". Fire this skill AND add the sfi.find_formula_references call (see Steps below).

When NOT to fire

Defer to another skill when:

• The user asks "what fields does X have?" That's a schema lookup, not impact analysis. Defer to answering-org-questions → sfi.list_components or sfi.get_component.
• The user asks "what's the convention for…" That's recognizing-naming-conventions. Naming patterns are observations, not impact.
• The user asks to refresh, init, or check vault status. Those fire refreshing-the-org-vault, /sfi-init, or pre-flight-checks.
• The user wants live data ("how many records reference this?"). the vault has no record-level data. Tell them to query their org directly.
• The user wants to modify metadata ("rename this field for me"). SfIntelligence is read-only. Tell them to use sf project deploy themselves.
• The user names a metadata type the refresh didn't model. Call sfi.coverage_report to see which families this vault retrieved, say which is missing plainly, and offer the closest partial.

Steps

Walk these in order. Each step has a definite output that feeds the next.

Step 0 — coverage before absence claims

For "safe to delete?", "nothing uses this", or "can I deprecate?":

1. sfi.coverage_report (or coverage from sfi.health_check).
2. sfi.safe_to_delete_field or sfi.get_impact as appropriate.
3. Render any coverageCaveat before the verdict. Fire vault-coverage-honesty when the user needs the honesty framing.

Empty impact with partial Report/FlexiPage/ListView coverage is not safety clearance.

Step 1 — Identify the target component ID

The user almost never types a canonical ID. They say "the Industry field on Account", "the Sales flow", "OpportunityService". Translate to the canonical form:

• CustomObject:{ApiName} — e.g., CustomObject:Account.
• CustomField:{Object}.{Field} — e.g., CustomField:Account.Industry__c.
• ValidationRule:{Object}.{RuleName} — e.g., ValidationRule:Account.Industry_Required.
• Flow:{ApiName} — e.g., Flow:Account_Onboarding.
• ApexClass:{ClassName} — e.g., ApexClass:OpportunityService.
• ApexTrigger:{TriggerName} — e.g., ApexTrigger:AccountTrigger.
• Layout:{Object}-{LayoutName} — e.g., Layout:Account-Account Layout.
• PermissionSet:{ApiName} — e.g., PermissionSet:Sales_Manager.
• Profile:{ApiName} — e.g., Profile:System Administrator.

If the user's phrasing maps unambiguously to one of these, use it directly. If it could match multiple components (e.g., "the status field" — which object?), don't guess. Either ask the user, or run sfi.search_components with the user's exact phrasing and surface the top matches for them to disambiguate.

Step 2 — Confirm the target exists (ALWAYS)

Do not skip this step, even when you derived the ID by translation in Step 1. sfi.get_impact now fails closed on an id it cannot place: an id matched by no node AND no referring edge returns error.kind: 'component-not-found' naming the id, rather than the empty slice it used to return — that empty slice was byte-identical to a real "nothing depends on this", so a typo read as a clean bill of health. Do not narrate a component-not-found as "nothing depends on this"; it means the walk never happened. Re-check the type prefix and spelling (sfi.resolve disambiguates a bare name).

Resolving first is still the cheaper path — sfi.resolve, or sfi.get_component with maxBodyBytes: 0 (the existence probe) — because it also catches the id that resolves to the WRONG component. Only report "no dependents" for an id that came back as a real component.

The ambiguity the error does not cover is the phantom: an id that IS referenced by other metadata but was never retrieved itself (typically a standard or managed-package component). It has referring edges, so the walk runs — impact.nodes comes back non-empty while impact.edges is empty, and the root is missing from its own node list. The tool does disclose this now: truncated is true, the disclosure says PARTIAL, names the phantom root, counts the collected edges it dropped, and points at sfi.find_component_usages on the same id (which reads the edge table without a node join). Check for the root in impact.nodes before narrating the slice, and follow the disclosure rather than reporting the thin slice as the answer.

If you ran sfi.search_components in Step 1, the top match (highest score) is usually right. Cite it explicitly to the user before proceeding: "I'm reading this as CustomField:Account.Industry__c — correct?" Don't proceed without that confirmation when there are 2+ high-scoring candidates.

Step 3 — Call sfi.get_impact

Default invocation:

{ "componentId": "CustomField:Account.Industry__c", "hops": 2 }

Notes on the parameters:

• hops defaults to 2 inside the handler, max 3. Don't go to 3 by default — the third hop typically pulls in distant transitively related components that aren't actionable. Use hops: 3 only when the user explicitly asks for a wider sweep ("show me the full transitive impact").
• edgeTypes is optional. Omit it for a full impact sweep; pass a subset (e.g., ['references', 'readsFrom']) when the user asks a type-specific question ("which validation rules and flows use this field?"). The foundational edge types include: references, readsFrom, writesTo, triggersOn, callsApex, parentOf, usedInLayout, grantedBy, listensTo — 20 in total; see docs/architecture.md §6 (or sfi.capabilities) for the full set.

The response shape:

{
  "data": {
    "impact": {
      "nodes": [ /* sorted by id ASC; includes the root unless it is a phantom */ ],
      "edges": [ /* incoming edges visited during BFS */ ]
    },
    "traversedEdgeTypes": [ /* edge types that appeared */ ],
    "diagram": "```mermaid\ngraph TD\n...\n```",
    "diagramOmittedReason": "diagram omitted: 84 nodes exceeds cap (30)"
  },
  "vaultState": { "sourceTreeHash": "...", "refreshedAt": "..." }
}

impact.nodes includes the root component when the vault holds a node row for it — which is the normal case, and an impact set of size 1 (just the root) then means "nothing in the emitted edge graph references this" (see the Honest-incomplete script section below).

It is NOT a guarantee. A phantom root — an id other metadata references but the refresh never retrieved — has no node row, so it is absent from its own impact.nodes. Measured on a real vault: an impact walk on a phantom standard object returned 14 nodes and 0 edges, none of the 14 being the root. Those 14 were its access-granting containers, connected to nothing. The tool no longer calls that slice complete — truncated is true, the disclosure reports it as PARTIAL, names the phantom root, counts the collected edges it dropped for a missing endpoint, and points at sfi.find_component_usages — but the check is still yours to make. Before you narrate a slice, confirm impact.nodes actually contains the id you asked about; if it does not, say the component itself is not in the vault rather than describing the leftovers as its dependents.

R6-19 — diagram. When the (already-capped) impact slice has 30 or fewer nodes, the response ALSO carries diagram: a ```mermaid graph TD ``` fence — the root as a circle, every other node a box labeled {ComponentType}: {apiName}, edges labeled by edgeType. Surface it verbatim when the user's client renders mermaid (a chat UI, an exported .html/.md file); it is a visual complement to the bucketed breakdown in Step 5, not a replacement — the bucketed narrative still carries confidence / source per edge, which the diagram does not. Above 30 nodes, diagram is ABSENT and diagramOmittedReason names the actual node count — never present a stale or partial diagram; tell the user the count exceeded the cap and narrow with hops / edgeTypes if they want a diagram-sized slice.

Step 4 — Optionally call sfi.run_analysis with { "name": "sfi.find_formula_references", "args": { … } }

If the user specifically asked about formulas ("find formulas using X", "which formula fields touch this?", "show me the formula references"), also call sfi.run_analysis with { "name": "sfi.find_formula_references", "args": { … } } for a focused list. Default invocation:

{ "fieldId": "CustomField:Account.Industry__c" }

This tool walks only the incoming references edges (the formula tokenizer's output) and enriches each result with the edge's source and properties — including tokenizedFromField, formulaLength, and the specific formula expression that referenced the target. The default limit is 50; max is 500.

Two honesty rules on this tool. The field must EXIST: an id naming no CustomField node — a miscased id, a typo, a field the refresh never retrieved — is refused with component-not-found plus typo-tolerant resolveSuggestions, so an empty referencers list is reserved for a real field that genuinely has none. And when the list IS empty, a coverageCaveat names whichever of the eleven families that produce references edges into a field (CustomField formulas, ValidationRule, ListView, ReportType, FlexiPage, QuickAction, WebLink, ApprovalProcess, MatchingRule, CustomMetadataRecord, Index) the vault did not fully retrieve. Render it: that zero reads "not checked in those families", never a proven "none".

Use this tool in addition to sfi.get_impact, not instead of it. get_impact walks every edge type; find_formula_references narrows the same data to the formula-only slice with richer per-reference metadata.

Step 5 — Organize the impact subgraph by component type

The raw response is a flat list of nodes and edges. The human reading needs a grouped, headlined view. Walk impact.nodes (excluding the root) and bucket by type. For each bucket, list:

• Component canonical ID.
• The edge type(s) that connect it back to the root (read from impact.edges where toId is the root or an intermediate hop).
• The edge's confidence.
• The edge's source (which extractor produced it — e.g., formula-tokenizer, flow-walker, permission-set-extractor).

Suggested ordering of buckets (most architect-relevant first):

1. Validation Rules (ValidationRule)
2. Flows (Flow)
3. Apex Triggers (ApexTrigger)
4. Apex Classes (ApexClass) — note the heuristic-Apex caveat below.
5. Layouts (Layout)
6. Permission Sets (PermissionSet)
7. Profiles (Profile)
8. Custom Fields / Custom Objects (CustomField, CustomObject)

Within each bucket, sort by component ID (the API already returns nodes sorted that way; preserve the order).

Step 6 — Cite canonical IDs and confidence

Every component named in the response gets its canonical ID in backticks. Every edge gets its confidence. Don't soften parsed into language that implies declared — and don't escalate parsed to declared even when the parser is highly reliable. The formula tokenizer is reliable, but its output is still parsed, not declared, because the formula text could in principle reference an alias the tokenizer normalizes imperfectly. The Flow walker is reliable, but Flow XML can contain inputReference expressions the walker only partially resolves (see Edge coverage below).

The confidence vocabulary, for this skill:

Step 7 — Disclose the coverage boundary

This step is non-optional. After the impact report, append a short disclosure that names the coverage gaps. Always, even when the impact set is large — the architect needs to know what isn't in the answer.

Template:

Impact analysis covers declared and parsed graph edges such as references, readsFrom / writesTo, triggersOn, callsApex, usedInLayout, lookupTo, grantedBy, and parentOf. Apex edges blend parsed (AST-backed) and heuristic (scanner-backed) tiers; dynamic Apex, string-built SOQL/SOSL, reflective field access, and metadata families missing from the vault coverage report can still be blind spots.

If the impact set has fewer dependents than the architect would expect from intuition, escalate the disclosure to the honest-incomplete script (next section).

The honest-incomplete script

Sometimes sfi.get_impact returns an empty or thin impact set for a component the architect knows is used somewhere — they remember writing Apex against it last quarter, or they recall a LWC that reads it. The graph may genuinely not record those references — heuristic Apex and frontend scanning can miss dynamic or reflective access.

When the result is empty (impact.nodes has only the root) or thin (fewer than ~3 dependents for a non-trivial field), don't pretend the analysis is complete. Use this script verbatim, adapted to the specific component:

The impact graph records {N} dependent(s) on {ComponentId}: {list}. This count is bounded by the current vault coverage and by heuristic static analysis. Dynamic Apex, string-built SOQL/SOSL, reflective field access, and metadata families absent from the vault can still hide dependencies. Treat an empty/thin result as a coverage signal, not proof that the component is unused. Try sfi.search_apex_source to grep the Apex source directly.

The point is to say "I see zero" and "zero might not mean zero." Architects making deprecation decisions need both halves.

Worked example

User asks: "What breaks if I change Account.Industry__c?"

Claude's flow:

1. Translate "the Industry field on Account" → CustomField:Account.Industry__c. Unambiguous; skip search_components.
2. Call sfi.get_impact with { componentId: 'CustomField:Account.Industry__c', hops: 2 }.
3. Receive (hypothetical): 8 nodes, 11 edges, traversed types ['grantedBy', 'parentOf', 'readsFrom', 'references', 'usedInLayout'].
4. Organize by type.
5. Respond:

Impact analysis for CustomField:Account.Industry__c (2-hop BFS over incoming edges, current coverage):

Validation Rules (2)

• ValidationRule:Account.Industry_Required — references, confidence: parsed, source formula-tokenizer.
• ValidationRule:Account.Enterprise_Industry_Check — references, confidence: parsed, source formula-tokenizer.

Flows (1)

• Flow:Account_Onboarding — readsFrom, confidence: parsed, source flow-walker.

Layouts (1)

• Layout:Account-Account Layout — usedInLayout, confidence: declared.

Permission Sets (2)

• PermissionSet:Sales_Manager — grantedBy, confidence: declared.
• PermissionSet:Sales_Rep — grantedBy, confidence: declared.

Parent Object

• CustomObject:Account — parentOf, confidence: declared.

Boundary: Apex analysis is heuristic rather than compiler-backed, and dynamic Apex, string-built SOQL/SOSL, reflective field access, or metadata families missing from the vault can hide dependencies. If you expect Apex to read this field, treat the gap as real and grep with sfi.search_apex_source.

Note what the response does and doesn't do:

• It cites every component by canonical ID.
• It cites every edge's confidence and source.
• It groups by type with counts.
• It includes the boundary disclosure even though the impact set is non-trivial.
• It does not assert "if you change this field, exactly these 8 things break" — it reports the impact graph's view, which is a subset of reality.

Edge coverage

The architect-facing summary of what's modeled, at what confidence:

The "Modeled?" + "Confidence" columns are the boundary you disclose: a heuristic "yes" still warrants a spot-check, and the no rows (dynamic SOQL/SOSL strings, reflective access) are real blind spots. Don't paraphrase this table — when in doubt, restate it.

Confidence discipline

Three rules. Cite confidence once per component listed; never aggregate across multiple edges of different confidence (surface both); never assert ground truth from parsed without naming the parser ("the formula tokenizer says X" is fine; "X depends on Y" for a parsed edge is not).

Common rationalizations

Red flags

Stop and surface the issue, or fire another skill, when:

• sfi.health_check returned status: 'degraded'/'unhealthy' or freshness.stale: true before the impact call. Stop. Route to /sfi-refresh (stale/degraded) or /sfi-init (missing vault). Impact analysis on stale data is worse than no analysis.
• sfi.get_impact returned { error: { kind: 'internal', message: 'graph query failed: ...' } }. Don't retry blindly — fire pre-flight-checks to diagnose the graph layer.
• The componentId you derived doesn't match any node (impact set is { nodes: [], edges: [] } — not even the root). This means Step 1's translation was wrong. Go back to sfi.search_components with the user's phrasing.
• The user wants impact analysis on an Apex method, not a class. get_impact nodes are class-level (ApexClass:OpportunityService), not method-level. Say so; offer class-level impact and route the method-precise question to sfi.call_graph / sfi.method_reachability.
• The user wants impact analysis on a metadata type the refresh didn't model. Don't guess — call sfi.run_analysis with { "name": "sfi.coverage_report", "args": { … } } to see which families this vault actually retrieved, say which is missing, and offer the closest partial via sfi.search_apex_source or sfi.search_flow_metadata.
• The impact result includes a node with confidence heuristic. That is expected — Apex method-body edges and frontend (LWC/Aura) references are heuristic by design. Don't flag it as a bug; cite the heuristic tier and recommend a source spot-check before the architect acts on it. (A heuristic edge to a missing node, however, is a phantom — disclose it as such.)
• The user is about to act on the impact report (deploy a deprecation, rename a field, delete a flow). Restate the coverage boundary explicitly before they act. Decision-time confidence matters more than terseness.

Verification

Before sending a response, confirm:

• I translated the user's component reference into a canonical ID (Type:Id), confirming via sfi.search_components when ambiguous.
• I called sfi.get_impact with hops: 2 (or 3 only on explicit request), and — for formula-focused questions — also sfi.find_formula_references.
• I organized the impact subgraph by component type, with each bucket labeled and counted.
• I cited every component's canonical ID, and every edge's edgeType, confidence, and source.
• I disclosed the coverage boundary explicitly — even when the impact set was non-trivial.
• If the impact set was empty or thin, I used the honest-incomplete script and pointed the user at sfi.search_apex_source for the Apex coverage gap.
• I did not paraphrase parsed as declared, and I did not assert ground truth from a parsed edge without naming the parser.
• If the user was about to act on the report, I restated the boundary first.
• When diagram was present, I surfaced it as a COMPLEMENT to the bucketed breakdown (not a replacement for confidence/source citations). When absent, I named diagramOmittedReason's node count rather than silently omitting the diagram with no explanation.

Grounding & routing (shared contract). For a vague or broad ask, call sfi.route_question first — in the default hybrid mode it returns a meaning-ranked toolCandidates shortlist (which YOU pick from) plus a suggested plane and a route hint (and whether to sfi.resolve a name first). Default tool profile is core: only the core spine (including sfi.live_consent) is directly invokable. For every other sfi.* analysis, call sfi.run_analysis with { "name": "sfi.<tool>", "args": { … } } (or follow route_question.invoke, which already wraps non-core steps). Optional: sfi.describe_analysis first when args are unclear. Every org fact must come from an sfi.* tool call, cited by its canonical id — never from memory. Build the answer only from what the tools returned, then pass it through sfi.synthesize_answer, which flags any hallucinatedIds (canonical ids no tool produced). Full cascade: using-sf-intelligence.