Answering Org Questions

Answering org questions

Usage & discovery (§C3 contract)

For "where is X used / who references X / what depends on X" — for ANY component type — call sfi.run_analysis with { "name": "sfi.find_component_usages", "args": { … } }, or the family specialist (find_field_anywhere for a field, find_code_usages for code, layout_assignments for a layout). Route by VERB: describe questions (what is / list / what values) use describe tools, NOT usage tools. Never improvise a multi-tool fan-out without citing evidence tiers. An empty result is "no static evidence in the vault" — NEVER "nothing uses this".

Overview

This skill is the conversational interface to the sf-intelligence vault. The flow: 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 (vault | live | hybrid | unknown) and a regex route as a HINT — then pick the tool(s) from the candidates, resolve any named component, check live consent if the live plane is needed, execute the tools, and use the rendered field when a tool returns one. Pick from the candidates rather than from feel; the route is a hint, not a command, and the seven-intent table below is the detail for executing each route. Always cite canonical component IDs in the answer.

The vault is the source of truth. The user is asking about their org, not a generic Salesforce org. General Salesforce knowledge tells you what OpportunityStage is; it does not tell you whether this org has a Custom_Stage__c. Every answer that names an org artifact must cite its canonical component ID (e.g., CustomField:Account.Industry__c) so the user can click through and verify. If the question requires capability the vault does not model — runtime Flow branch evaluation, dynamic Apex dispatch the static graph cannot see, or live record data when the live plane is disabled — say so plainly. Never invent.

When to fire

Fire this skill when the user asks a structured question about the org or the vault. Concrete triggers:

• Schema questions. "What fields does Account have?" "Show me Opportunity's structure." "What objects exist in this org?"
• Dependency questions. "What triggers fire on Account?" "What flows reference Industry__c?" "What uses OpportunityService?"
• Permission questions. "Who can read Industry__c?" "What does the Sales_Manager permission set grant?" "Which profiles allow MyClass.apxc?"
• Naming or convention questions. "What's our convention for status fields?" "Should I name this Foo__c or Bar__c?" "Do we use _Date__c or _On__c suffixes?"
• Apex source questions. "Find any class that mentions Database.upsert." "Show me triggers that touch Industry__c." "Where do we call MyClass.process?"
• Flow metadata questions. "Which flows have a Start on Account?" "Where does My_Flow reference a field?"
• Manifest or health questions. "When was the vault last refreshed?" "Is the data still fresh?" "How many components are vaulted?"

When NOT to fire

Defer to another skill or to general knowledge when:

• The user wants to refresh. "Refresh the vault", "pull latest", "I just deployed metadata", /sfi-refresh. Fire refreshing-the-org-vault instead.
• The vault doesn't exist yet. No org-kb/ directory. sfi.health_check returns status: 'unhealthy' with checks.vaultExists: false. Tell the user to run /sfi-init first; don't try to answer from no data.
• The user is asking a generic Salesforce question with no reference to their org. "What is a permission set?" "How does Apex work?" These are general-knowledge questions, not vault questions. Answer briefly from general knowledge and offer to look at how their org uses the concept.
• The user wants live data and the live plane is off. "How many Accounts closed today?" Offer to enable the live plane once (sfi.live_consent { grant: true }), then use sfi.live_count / sfi.live_sample; otherwise name the boundary and point to sf data query.
• The question needs runtime Apex semantics (dynamic dispatch, values only known at run time). Use static tools (sfi.explain_apex_method, sfi.call_graph) and say what is not provable offline.
• The question needs runtime Flow branch choice for a specific record. sfi.explain_flow is structural; it does not evaluate record state.

Route first (the front door)

Before the manual classification below, call sfi.route_question with the user's question. It returns plane (vault | live | hybrid | unknown), the ordered sfi.* tools, needsResolve (resolve a named component first?), liveRequired (needs the opt-in live plane?), and a gap when no dedicated tool exists yet. Then:

1. If needsResolve, sfi.resolve the component and act on its disposition.
2. If liveRequired and the live plane is off, do not infer from the vault — offer to enable it once: sfi.live_consent { grant: true } (read-only, persists per org). Proceed live only after consent / SFI_LIVE_PLANE_ENABLED=1 / liveEnabled: true.
3. Execute the tools in order. When a result carries a rendered field, use it as the prose/table answer and keep its provenance + freshness stamp.
4. On plane: 'unknown' (or a gap), say the capability isn't built yet — the question is logged for the backlog — and offer the closest thing. Never invent.

The seven-intent table below is the fallback when you pick a tool by hand, and the reference for what each route does.

Classify the intent

Every org question maps to exactly one of these seven intents. Pick one before reaching for a tool. If you can't pick — if the question seems to straddle two — pick the more specific one first; if it goes thin, escalate to the broader one.

A few cues to break ties:

• The question names a canonical ID (Account.Industry__c, MyClass.apxc) → schema or dependency, not source. Search the vault first; only grep source if the vault is thin.
• The question asks "what uses X" or "what depends on X" → dependency, not schema.
• The question asks about a pattern across many components ("what's the convention", "do we always …") → naming/convention.
• The question asks "when", "how fresh", "how many components" → that's about the vault itself, not its contents → manifest/health.

Pick the tool

Before any primary call, confirm vault freshness. The using-sf-intelligence skill already requires this — sfi.health_check at the start of every org-touching session. If you skipped it because a previous turn already ran it, that's fine; if it's the first turn, run it now. A stale vault returns confident wrong answers.

Two rules for tool inputs:

• Use the user's exact phrasing first. Don't translate "rep" into "owner" unless the first search returns nothing.
• Pass types to sfi.search_components only when the user's question pins the type. Guessed types cuts off real matches.

Escalation cascade

When the first call is thin, the next move is mechanical, not creative. Follow this table:

If two tool calls in a row return errors that aren't in this table, stop and fire the pre-flight-checks skill rather than retrying blindly.

Cite component IDs

Every answer that names an org artifact must cite its canonical component ID in backticks. The format is Type:Id:

• CustomObject:Account
• CustomField:Account.Industry__c
• ValidationRule:Account.Industry_Required
• Flow:My_Flow
• ApexClass:OpportunityService
• ApexTrigger:AccountTrigger
• Layout:Account-Account Layout
• PermissionSet:Sales_Manager
• Profile:System Administrator

Acceptable:

CustomField:Account.Industry__c is a picklist with 7 values, used by Layout:Account-Account Layout and granted by PermissionSet:Sales_Manager.

Unacceptable:

The Account has an Industry field that's on the layout and granted to the Sales Manager profile.

Two reasons this matters. First, the user can navigate from the ID to org-kb/components/<Type>/<path>.md and verify the claim. Second, the ID format is how Claude proves to itself it's reading the vault and not pattern-matching from general knowledge of Salesforce. If you find yourself writing a sentence about an org artifact without a backticked ID, that's a signal you're guessing — stop and call a tool.

Confidence discipline

Edges in the vault carry a confidence field. There are three values, and they have very different semantics:

• declared — the relationship is in Salesforce metadata itself (e.g., CustomObject parentOf CustomField, Layout usedInLayout CustomField). This is ground truth. Cite without caveat.
• parsed — extracted by parsing Apex or Flow source (AST / walker). Stronger than heuristic, weaker than declared metadata. Cite normally; note it is static analysis, not runtime proof.
• heuristic — the relationship is inferred from patterns (e.g., naming-convention observations, "fields with _Date__c suffix tend to be …"). This is a hypothesis. Cite it explicitly as heuristic:

  "By naming convention, CustomField:Account.Last_Contact_Date__c looks like it belongs to the date-suffix family. This is a heuristic observation — not a declared dependency. Verify before acting."

When sfi.get_naming_convention_report returns observations, every observation is heuristic by definition. Surface that. Don't write "the convention is X" — write "based on N observed samples (heuristic confidence), most date fields in this scope use suffix X."

Destructive verdicts and SAST

Before sfi.safe_to_delete_field, destructive what_if_* tools, or high-stakes SAST answers (sfi.crud_fls_audit, sfi.governor_limit_risks):

1. Call sfi.run_analysis with { "name": "sfi.coverage_report", "args": { … } } (or read coverage from sfi.health_check) when completeness is unknown.
2. Run the destructive or audit tool.
3. If the response includes coverageCaveat, render it before the verdict. Partial coverage means absence in an unchecked family is not checked, never none.

For repeat false positives the user has already reviewed, call sfi.baseline_acknowledge with the exact tool, rule, componentId, and location from the finding. sfi.baseline_status lists what is suppressed; audit tools expose suppressedFindingCount / suppressedRiskCount alongside active findings.

Change intelligence over time

The vault is a snapshot at refresh time, but you can compare snapshots and surface freshness:

If no snapshots exist, say so and offer sfi snapshot create --label <name> after the next /sfi-refresh. Tooling API enrichment (sfi refresh --with-tooling-api) improves lastModifiedBy / lastModifiedDate on supported types.

When the vault still can't answer

Refuse honestly. Offer the partial answer you can give. Examples:

Pattern: name the boundary (offline vs live, static vs runtime, coverage gap), then offer the right tool.

Common rationalizations

Red flags

Stop and ask the user, or fire another skill, when:

• sfi.health_check returns status: 'degraded'/'unhealthy' or freshness.stale: true. Stop answering. Route to /sfi-init (missing vault) or /sfi-refresh (stale snapshot).
• The user's question pivots to live data or runtime semantics. Route to sfi.live_* when enabled, or name the boundary and stop.
• Two consecutive tool calls return errors. Don't retry blindly — fire pre-flight-checks.
• A heuristic edge is about to drive a deployment decision. Make the confidence explicit before the user acts on it.
• The user asks about a type with neverModeled or zero retrieve in sfi.coverage_report. Say "not checked", not "none".
• You're about to write a sentence about an org artifact without citing its canonical ID. That's a signal you're guessing. Stop; call a tool.
• The user asks you to commit, deploy, or modify metadata. Read-only product. Tell them to use sf project deploy themselves.

Verification

Before sending a response, confirm:

• I classified the question into exactly one of the seven intents.
• I called the primary tool for that intent, and if the result was thin, I followed the escalation cascade — not improvised.
• I cited the canonical component ID (Type:Id in backticks) for every org artifact I named.
• I built the answer ONLY from tool output and ran it through sfi.synthesize_answer — hallucinatedIds is empty (no ID in my prose that a tool did not return).
• If I reported an edge, I cited its confidence level (declared / parsed / heuristic).
• If I couldn't answer, I named the boundary (live vs offline, runtime vs static, coverage gap) and offered the partial tool path.
• If sfi.health_check flagged the vault as degraded, unhealthy, or freshness.stale, I stopped and routed the user to /sfi-init or /sfi-refresh instead of answering.
• For destructive or absence-based answers, I checked coverage and surfaced any coverageCaveat before the verdict.
• For change-over-time questions, I used sfi.trend / sfi.diff_snapshots / sfi.changed_since (or named the snapshot prerequisite) instead of inventing history.
• I did not blend vault data with generic Salesforce memory. Every claim about this org came from a tool call.