@ryanstark24/sfgraph-skills 1.1.4 → 1.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryanstark24/sfgraph-skills",
-  "version": "1.1.4",
+  "version": "1.6.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -22,7 +22,7 @@
     "url": "https://github.com/ryanStark24/sfgraph"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22"
   },
   "publishConfig": {
     "access": "public"
@@ -30,6 +30,7 @@
   "description": "sfgraph SKILL.md playbooks for Cursor and Claude",
   "files": [
     "dist",
+    "!dist/**/__tests__",
     "skills",
     "README.md"
   ],

package/skills/sf-cross-layer-trace/SKILL.md

@@ -21,6 +21,10 @@ tools_used:
 
 Use when the user needs to follow a single artifact (field, LWC, Apex method) across every layer it touches — UI rendering, Apex controller, flow automation, data model.
 
+## Evidence rule — say it only if something backs it
+
+State a fact about this org or the Salesforce platform **only when evidence backs it**: a tool/graph result, source you actually read (local sfdx file or an org fetch), a live org query, or official Salesforce documentation. If you don't have that, say so plainly — "the graph doesn't show this", "unverified", "I'd need to check the org" — and either go get the evidence or stop. **Never fill the gap with a plausible-sounding guess**: an invented field/method/object name, an assumed dependency, or a governor number recalled from memory. Label each claim as **graph-confirmed** (a tool returned it), **inferred** (you reasoned it from graph facts — say which facts), or **general Salesforce knowledge**. For platform behaviour — governor limits, order of execution, sharing/FLS semantics, API rules — cite the official doc (developer.salesforce.com; fetch it if unsure) instead of asserting from memory. If the graph is stale or the org was never ingested, lead with that caveat — your grounding may be wrong.
+
 ## When to volunteer this skill
 
 Source-only tools (file grep, repo search, `explain_code`) can answer "where is this used?" inside the sfdx-source repo, but they cannot see:
@@ -37,16 +41,17 @@ Only skip the offer when the user has explicitly scoped the question to source (
 
 ## Playbook
 
-1. Resolve the starting node. If the user gave a field, call `analyze_field` first to canonicalise `SObject.Field` and gather direct readers/writers.
-2. Call `cross_layer_flow_map` with the resolved node. Receive ordered paths across layers (UI -> Controller -> Service -> Selector -> SObject and any Flow / Process Builder branches).
-3. For each distinct path, summarise the layer transitions with the edge type that bridges them (`@wire`, `@AuraEnabled`, `READS_FIELD`, `UPDATES_FIELD`, `INVOKES_FLOW`).
+1. Resolve the starting node. `cross_layer_flow_map` walks **downstream only**, from an `entry` (LWC, Aura, page, Flow, Apex, OmniScript, FlexCard, Integration Procedure) toward the data it touches. A field or object entry reaches nothing.
+   - **"Where is this field / component used"** is an upstream question: call `analyze_field(object, field)` for a field's direct readers and writers, or `trace_upstream` on the component's qname for the pages and components that reach it. Then run step 2 from each UI or automation entry you found.
+2. Call `cross_layer_flow_map(entry=…)` with the resolved entry. Receive ordered paths across layers (UI -> Controller -> Service -> Selector -> SObject and any Flow / Process Builder branches).
+3. For each distinct path, summarise the layer transitions with the edge type that bridges them (`@wire`, `@AuraEnabled`, `READS_FIELD`, `WRITES_FIELD`, `FLOW_INVOKES_APEX`).
 4. Surface anything anomalous: cycles, missing `with sharing`, fields read by multiple LWCs but written only by Flow, etc.
 5. Render the Mermaid layered diagram from `cross_layer_flow_map`. If the graph has more than 30 nodes, ask whether to filter to a single layer pair.
 6. End with a one-line recommendation of which related skill to invoke next (e.g. `sf-security-audit` if FLS gaps appear).
 
 ## Visualization
 
-Render a **`flowchart TD`** layered diagram with one subgraph per layer (UI / Controller / Service / Selector / Data). Edges are labelled with the edge type that bridges layers (`@wire`, `@AuraEnabled`, `READS_FIELD`, `UPDATES_FIELD`, `INVOKES_FLOW`).
+Render a **`flowchart TD`** layered diagram with one subgraph per layer (UI / Controller / Service / Selector / Data). Edges are labelled with the edge type that bridges layers (`@wire`, `@AuraEnabled`, `READS_FIELD`, `WRITES_FIELD`, `FLOW_INVOKES_APEX`).
 
 ```
 flowchart TD
@@ -65,8 +70,14 @@ flowchart TD
 
 If the resolved trace has >30 nodes, ask the user to narrow to a single layer-pair before rendering — a sprawling layered diagram is more misleading than no diagram.
 
+## Trace-tool noise defaults
+
+If you drop down to `trace_upstream` / `trace_downstream` for a raw dependency walk, note they **hide security-grant and inferred edges by default**. A class granted to 100+ profiles, or a Vlocity node with reflection-walker string-name matches, would otherwise drown the real dependencies. The response tells you "N edges hidden". Only pass `include_security: true` for an access-centric question, or `include_inferred: true` when the user explicitly wants low-confidence reflection links. Use `rel_types: [...]` to pin a walk to specific relationships (e.g. `["CALLS","IS_TEST_FOR"]`). `cross_layer_flow_map` is unaffected — it already follows curated layer edges.
+
 ## Staleness check
 
+If `staleness_check` is not available (the server runs with `SFGRAPH_TOOLS=core`), skip this step and say the graph's freshness was not checked.
+
 Before calling `cross_layer_flow_map`, invoke `staleness_check` for the target org. If the report says stale, surface a warning to the user:
 
 > Your ingest is N days old. Run `sfgraph ingest --org <alias>` to refresh, or proceed with the understanding that the graph may not reflect recent changes.
@@ -84,7 +95,7 @@ Then continue with the playbook.
 ## Don't
 
 - Do not collapse layers — the value of this skill is showing the layer boundaries explicitly.
-- Do not include nodes outside the requested traversal depth; defer breadth to a follow-up call.
+- `cross_layer_flow_map` has no depth parameter; if its map is too broad, narrow by starting from a nearer entry, or use `trace_downstream` with `depth`.
 - Do not modify anything. Pure read.
 - Do not assume the starting node exists; if `analyze_field` returns empty, ask the user to refine.
 - Do not stop at a source-only answer for LWC / Aura / ApexPage / field / Apex method questions without at least *offering* the cross-layer trace. Repo grep misses FlexiPage bindings, Quick Action targets, and the Apex→SObject tail — say so and offer to fill it in.

package/skills/sf-cross-org-diff/SKILL.md

@@ -18,10 +18,14 @@ tools_used:
 
 Use when the user wants to understand drift between two orgs — typically pre-deploy verification or post-deploy reconciliation.
 
+## Evidence rule — say it only if something backs it
+
+State a fact about this org or the Salesforce platform **only when evidence backs it**: a tool/graph result, source you actually read (local sfdx file or an org fetch), a live org query, or official Salesforce documentation. If you don't have that, say so plainly — "the graph doesn't show this", "unverified", "I'd need to check the org" — and either go get the evidence or stop. **Never fill the gap with a plausible-sounding guess**: an invented field/method/object name, an assumed dependency, or a governor number recalled from memory. Label each claim as **graph-confirmed** (a tool returned it), **inferred** (you reasoned it from graph facts — say which facts), or **general Salesforce knowledge**. For platform behaviour — governor limits, order of execution, sharing/FLS semantics, API rules — cite the official doc (developer.salesforce.com; fetch it if unsure) instead of asserting from memory. If the graph is stale or the org was never ingested, lead with that caveat — your grounding may be wrong.
+
 ## Playbook
 
 1. Call `list_orgs` first. Present the user with the authenticated orgs, each org's `ingested` flag, last sync timestamp, and `stale` flag. Ask the user to pick the two orgs to compare. Refuse to proceed if either selected org has `ingested=false` — instruct them to run `sfgraph ingest --org <alias>` first.
-2. Call `cross_org_diff(orgA, orgB)`. Capture added / removed / modified nodes grouped by metadata category.
+2. Call `cross_org_diff(org_a, org_b)` (optionally `category`). Capture added / removed / modified nodes grouped by metadata category. Managed-package and standard items found in one org only are hidden by default and counted in the report; pass `include_managed: true` / `include_standard: true` only when the user asks about them.
 3. For high-churn categories, call `point_in_time_diff` inside each org to confirm the drift originated there (vs being a stale snapshot artifact).
 4. Categorise drift: **structural** (new objects/fields), **logic** (Apex, Flow body changes), **security** (profile / sharing), **config** (custom metadata / settings).
 5. Render the Mermaid drift summary from the tool. For each category, list the top-N items by impact.
@@ -48,6 +52,8 @@ For diffs with >50 nodes, switch to a bucketed table per category and skip the d
 
 ## Staleness check
 
+If `staleness_check` is not available (the server runs with `SFGRAPH_TOOLS=core`), skip this step and say the graph's freshness was not checked.
+
 Before calling `cross_org_diff`, invoke `staleness_check` for both orgs. If either is stale, surface a warning to the user:
 
 > Your ingest for `<alias>` is N days old. Run `sfgraph ingest --org <alias>` to refresh, or proceed with the understanding that the graph may not reflect recent changes.

package/skills/sf-dead-code-audit/SKILL.md

@@ -19,16 +19,21 @@ tools_used:
 
 Use when the user wants to inventory metadata that appears unreferenced. Output must be bucketed by confidence — deletion in Salesforce is reversible only via backup, so we communicate uncertainty.
 
+## Evidence rule — say it only if something backs it
+
+State a fact about this org or the Salesforce platform **only when evidence backs it**: a tool/graph result, source you actually read (local sfdx file or an org fetch), a live org query, or official Salesforce documentation. If you don't have that, say so plainly — "the graph doesn't show this", "unverified", "I'd need to check the org" — and either go get the evidence or stop. **Never fill the gap with a plausible-sounding guess**: an invented field/method/object name, an assumed dependency, or a governor number recalled from memory. Label each claim as **graph-confirmed** (a tool returned it), **inferred** (you reasoned it from graph facts — say which facts), or **general Salesforce knowledge**. For platform behaviour — governor limits, order of execution, sharing/FLS semantics, API rules — cite the official doc (developer.salesforce.com; fetch it if unsure) instead of asserting from memory. If the graph is stale or the org was never ingested, lead with that caveat — your grounding may be wrong.
+
 ## Playbook
 
-1. Call `dead_code_audit` over the user's chosen scope (entire org, single namespace, or one metadata category). Capture every candidate plus the evidence the tool used (no incoming edges, no inclusion in deploy manifests, etc.).
-2. Call `freshness_report` to layer last-touched timestamps onto each candidate. Stale + unreferenced is stronger evidence than unreferenced alone.
+1. Call `dead_code_audit` for the org. The tool **summarizes by confidence (`high`/`medium`/`low`) and by metadata type**, then renders a capped list (`limit`, default 50). On a large org there can be thousands of candidates — do NOT try to retrieve them all inline; work from the summary counts and drill in with `confidence: "high"` (most-likely-dead first) or raise `limit`. For the complete machine-readable set, use `export_sarif`. Each row carries a score + reasons (`no_incoming_edges`, `test_class` — an `@isTest` class nothing references, flagged `isTest: true`, `stale_freshness`). Test references count as references: production code that only tests reference is not dead and is listed apart in `referencedOnlyByTests` (reason `referenced_only_by_tests`); deleting it means deleting those tests too.
+   - **Unused fields:** call `dead_code_audit(label="CustomField")` (optionally `pattern="CustomField:Account.*"`). It lists fields that nothing reads or writes. A field on a page layout or in a report still counts as used; profile and permission-set access does not. Fields have no freshness score, so there is no confidence grade: treat each one as **likely-dead** until checked.
+2. Confidence already reflects last-modified dates (`stale_freshness`). `freshness_report` is an org-wide view of what changed recently (20 rows per bucket); it cannot be filtered to the candidates, so use it only for context, not per candidate.
 3. For any candidate the user names interactively, call `trace_upstream` to confirm absence of indirect callers (dynamic Apex, Flow lookups, callable interfaces). Optionally call `find_similar(qname=<candidate>, k=5)` — if the candidate has near-neighbours (similarity > 0.6) that ARE referenced, the candidate may be a copy-paste duplicate of live code and worth deleting; if every neighbour is also in the dead list, you've found a whole disused subsystem worth flagging as a group.
 4. Sort candidates into three buckets:
    - **confident-dead** — no incoming edges, no dynamic-invocation signature match, freshness > 12 months, no inclusion in active permission sets / page layouts.
    - **likely-dead** — no incoming edges, but at least one weak signal (recently modified, referenced from a managed package boundary, or named in a metadata file we don't parse fully).
    - **suspicious-uncertain** — looks dead but the graph has known blind spots (dynamic SOQL string-interpolated field name, reflection-style `Type.forName`, external system reference).
-5. Render the Mermaid bar-chart / treemap returned by the tool grouped by category.
+5. Render a bar-chart / treemap as Mermaid yourself, grouped by category, by counting the candidates the report lists (each line names its kind and confidence). The tool does not draw a diagram.
 6. For confident-dead items, propose a destructive-changes.xml snippet but do not save it. The user owns the delete decision.
 
 ## Visualization
@@ -50,6 +55,8 @@ When the org has >100 dead candidates, drop the diagram and rely on the per-buck
 
 ## Staleness check
 
+If `staleness_check` is not available (the server runs with `SFGRAPH_TOOLS=core`), skip this step and say the graph's freshness was not checked.
+
 Before calling `dead_code_audit`, invoke `staleness_check` for the target org. Stale ingests make dead-code analysis dangerously wrong (a recently-added caller would be invisible). If the report says stale, surface a warning to the user:
 
 > Your ingest is N days old. Run `sfgraph ingest --org <alias>` to refresh, or proceed with the understanding that the graph may not reflect recent changes.

package/skills/sf-debug-log-analysis/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: sf-debug-log-analysis
+description: Read and analyse a Salesforce Apex debug log — exceptions/FATAL_ERROR, governor-limit consumption (SOQL/DML/CPU/heap), the execution call tree, and slow or repeated code units — then ground every finding in the org graph (map the log's code units/methods to qnames and explain WHY with trace/governor/analyze_field). Use when the user pastes or points to a debug log, an `sf apex get log` output, or asks to interpret a System.debug / stack trace / "Too many SOQL queries" / CPU-time log. Pairs with sf-debug-root-cause (log = symptom, graph = cause).
+triggers:
+  - "debug log"
+  - "read this log"
+  - "analyze this log"
+  - "apex log"
+  - "Too many SOQL queries"
+  - "Apex CPU time limit"
+  - "System.debug output"
+  - "FATAL_ERROR"
+  - "LIMIT_USAGE"
+  - "sf apex get log"
+  - "stack trace from the log"
+tools_used:
+  - find_nodes
+  - explain_code
+  - trace_upstream
+  - trace_downstream
+  - analyze_field
+  - governor_risk_check
+  - staleness_check
+---
+
+# sf-debug-log-analysis
+
+A Salesforce debug log is the ground truth of what *actually executed* — but on its own
+it's a wall of pipe-delimited lines and it can't tell you *why* (what other code calls the
+slow method, where the in-loop SOQL is declared, what writes the field that reverted).
+This skill reads the log, extracts the signal, and **grounds each finding in the org graph**
+so the answer is "the CPU went here because `OrderTriggerHandler.recalc` runs a SOQL inside
+a `for` over `Trigger.new` — here are its 3 callers", not "looks like a CPU issue".
+
+Format reference: <https://developer.salesforce.com/docs/atlas.en-us.apexcode.meta/apexcode/apex_debugging_debug_log.htm>
+
+## Evidence rule — say it only if something backs it
+
+State a fact about this org or the Salesforce platform **only when evidence backs it**: a tool/graph result, source you actually read (local sfdx file or an org fetch), a live org query, or official Salesforce documentation. If you don't have that, say so plainly — "the graph doesn't show this", "unverified", "I'd need to check the org" — and either go get the evidence or stop. **Never fill the gap with a plausible-sounding guess**: an invented field/method/object name, an assumed dependency, or a governor number recalled from memory. Label each claim as **graph-confirmed** (a tool returned it), **inferred** (you reasoned it from graph facts — say which facts), or **general Salesforce knowledge**. For platform behaviour — governor limits, order of execution, sharing/FLS semantics, API rules — cite the official doc (developer.salesforce.com; fetch it if unsure) instead of asserting from memory. If the graph is stale or the org was never ingested, lead with that caveat — your grounding may be wrong.
+
+## Getting the log (if the user hasn't supplied one)
+
+- Salesforce CLI: `sf apex list log` → `sf apex get log --log-id <id> > debug.log`, or live: `sf apex tail log --color none`.
+- Setup → Debug Logs (trace flags on the user), then download.
+- Tell the user the log level matters: `Apex Code = FINE`/`FINER` captures method entry/exit and SOQL; `Apex Profiling`/`System = FINE` captures the `CUMULATIVE_LIMIT_USAGE` block. `FINEST` is huge and often truncated at the 20 MB cap — prefer `FINE`/`FINER` unless you need variable-level detail.
+
+## Reading the log (format)
+
+The header line lists the API version + per-category log levels. Every subsequent line is
+`HH:mm:ss.SSS (elapsedNanos)|EVENT_TYPE|details`. The event types that carry signal:
+
+| Event | What it tells you |
+|---|---|
+| `CODE_UNIT_STARTED` / `_FINISHED` | The unit boundaries — triggers, `Class.method`, flows, VF, anonymous. Top of the call tree. |
+| `METHOD_ENTRY` / `METHOD_EXIT` | Method call tree (needs Apex Code ≥ FINER). Indentation/elapsed time = where time goes. |
+| `SOQL_EXECUTE_BEGIN` / `_END` | Each query + `Rows:` returned + aggregations. **Count them** — repeated identical SOQL = in-loop. |
+| `SOSL_EXECUTE_*`, `DML_BEGIN` / `_END` | SOSL and DML operations + row counts. |
+| `CALLOUT_REQUEST` / `_RESPONSE` | HTTP callouts + endpoints + timing. |
+| `EXCEPTION_THROWN` | The thrown exception + type + the offending `Class.method: line`. |
+| `FATAL_ERROR` | The uncaught error + full Apex stack trace — the prime anchor for a failure. |
+| `USER_DEBUG` | `System.debug()` output the developer planted. |
+| `LIMIT_USAGE_FOR_NS` / `CUMULATIVE_LIMIT_USAGE` | **The governor scorecard** — SOQL queries, query rows, DML statements/rows, CPU time, heap, callouts used vs limit. |
+| `HEAP_ALLOCATE`, `STATEMENT_EXECUTE`, `VARIABLE_*` | FINEST-only, very noisy — skip unless chasing a heap/variable bug. |
+| `FLOW_*` / `WF_*` | Flow elements and Workflow-rule evaluation (order-of-execution bugs). |
+
+## Method
+
+1. **If the log is large, filter before reading.** Don't load a 20 MB log into context. Grep for the signal first:
+   `grep -nE 'FATAL_ERROR|EXCEPTION_THROWN|CUMULATIVE_LIMIT_USAGE|LIMIT_USAGE_FOR_NS' debug.log` for failures + limits;
+   `grep -c 'SOQL_EXECUTE_BEGIN' debug.log` for query count;
+   `grep -E 'CODE_UNIT_(STARTED|FINISHED)' debug.log` for the unit skeleton.
+   Read only the relevant slices.
+2. **Classify the problem** from the evidence: an uncaught failure (`FATAL_ERROR`), a governor breach (limit at/over 100% in the cumulative block, or a `System.LimitException`), a performance issue (one `CODE_UNIT` dominating elapsed time), or just `USER_DEBUG` tracing.
+3. **Extract the anchor:**
+   - Failure → the exception type + the top in-org frame `Class.method: line` from the stack trace.
+   - Governor → which limit, the count vs cap, and the `CODE_UNIT`/method where consumption spiked (repeated SOQL/DML lines under one unit).
+   - Performance → the `CODE_UNIT`/method with the largest elapsed delta.
+4. **Ground it in the graph** (the part a log reader alone can't do):
+   - `find_nodes ApexClass:<Name>` / `ApexMethod:<Name>.*` to resolve the anchor to a qname; `explain_code` reads stored source for Apex methods, trigger bodies (`ApexTrigger:<Name>`), and Flows (`Flow:<Name>`). For a **whole class, LWC JS, or managed code the graph has no source** — fetch it (local `force-app/main/default/{classes,triggers,flows}/...` or `sf project retrieve start -m "ApexTrigger:<Name>"`); don't analyse from an empty stub. See `sf-explain-code`.
+   - `trace_upstream` — who invokes this unit, and in what context (trigger vs batch vs LWC). Order-of-execution and "why was this even called" answers live here.
+   - `trace_downstream` — what it calls/reads/writes; a NullPointer or limit usually originates in a callee.
+   - Governor breach → `governor_risk_check` (it scans the whole org; keep the findings for that class) to find the in-loop query or DML the log proved is hot. Its evidence is the query text or DML target, not a line number.
+   - Field misbehaviour seen in the log → `analyze_field` for every trigger/Flow/validation that fires on that field (competing automation).
+5. **State a single root-cause hypothesis** backed by *both* the log evidence and the graph evidence, then hand the fix to the right design skill (`sf-architect-apex` / `sf-architect-performance` / `sf-governor-risk-fix`) — grounded, never generic.
+
+## Staleness
+
+If you'll ground in the graph, call `staleness_check` first. A stale graph maps the log's
+code units to outdated source — warn and recommend `sfgraph ingest --org <alias>`. The log
+itself is always current; the mismatch is on the graph side.
+
+## Response shape
+
+- **Verdict** — one line: failure / governor breach / performance / trace-only, with the anchor `Class.method:line`.
+- **Log evidence** — the decisive lines (exception, the cumulative-limit row that breached, the repeated SOQL count, the dominant code unit) — quote them, don't paraphrase.
+- **Graph grounding** — callers, callees, competing automation, or the in-loop source line that explains the log.
+- **Root cause** — one hypothesis, confidence, tied to both evidence sources.
+- **Fix** — described and handed off to a design skill; not auto-applied.
+- **Mermaid** — optional call-tree or caller→unit→callee path when it clarifies.
+
+## Don't
+
+- Don't load a multi-MB log wholesale — filter with grep first, then read slices. Say what you filtered so nothing looks silently dropped.
+- Don't stop at the log. The log shows *what*; grounding in the graph shows *why* — that's the value. A log-only answer is a guess about the cause.
+- Don't trust `FINEST` noise (`STATEMENT_EXECUTE`/`VARIABLE_ASSIGNMENT`) as signal — anchor on CODE_UNIT/SOQL/DML/limit/exception events.
+- Don't edit code here — produce evidence + root cause; design hands off.
+- Don't confuse a logged, *caught* `EXCEPTION_THROWN` with the actual failure — the uncaught `FATAL_ERROR` (if present) is the one that ended the transaction.

package/skills/sf-debug-root-cause/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: sf-debug-root-cause
+description: Root-cause a SPECIFIC Salesforce failure — an Apex exception or stack trace, a failing test, a flow fault, or "this field/record isn't behaving right" — by grounding the symptom in the org graph (callers, callees, recent changes, automation on the object, test coverage). Use when the user reports a concrete error/symptom and wants to know WHY. For "what changed since deploy" broadly use sf-what-broke; for pre-commit blast radius use sf-wip-impact.
+triggers:
+  - "why is this failing"
+  - "debug this error"
+  - "this test fails"
+  - "stack trace"
+  - "NullPointerException"
+  - "System.LimitException"
+  - "this trigger isn't firing"
+  - "field isn't updating"
+  - "flow fault"
+  - "root cause"
+tools_used:
+  - find_nodes
+  - explain_code
+  - trace_upstream
+  - trace_downstream
+  - analyze_field
+  - what_broke
+  - test_gap_intelligence_from_git_diff
+  - staleness_check
+---
+
+# sf-debug-root-cause
+
+Use when the user has a **concrete failure** and wants the cause, not a guess. Salesforce
+failures are rarely in the one method that threw — they come from another trigger on the
+same object, a recent change upstream, an order-of-execution surprise, or automation the
+developer forgot exists. The graph makes those visible. Debug by narrowing with evidence,
+never by pattern-matching the error message to a generic fix.
+
+## Evidence rule — say it only if something backs it
+
+State a fact about this org or the Salesforce platform **only when evidence backs it**: a tool/graph result, source you actually read (local sfdx file or an org fetch), a live org query, or official Salesforce documentation. If you don't have that, say so plainly — "the graph doesn't show this", "unverified", "I'd need to check the org" — and either go get the evidence or stop. **Never fill the gap with a plausible-sounding guess**: an invented field/method/object name, an assumed dependency, or a governor number recalled from memory. Label each claim as **graph-confirmed** (a tool returned it), **inferred** (you reasoned it from graph facts — say which facts), or **general Salesforce knowledge**. For platform behaviour — governor limits, order of execution, sharing/FLS semantics, API rules — cite the official doc (developer.salesforce.com; fetch it if unsure) instead of asserting from memory. If the graph is stale or the org was never ingested, lead with that caveat — your grounding may be wrong.
+
+## Method (scientific, evidence-first)
+
+0. **If a debug log is available, start there.** A debug log is the strongest anchor — it
+   has the exact `FATAL_ERROR` stack frame and the real governor scorecard. Hand the log to
+   **`sf-debug-log-analysis`** to extract the anchor + limit evidence, then continue this
+   playbook from step 2 with that anchor. Without a log, anchor from the error text/symptom:
+
+1. **Anchor the symptom to a node.** Parse the error / test name / symptom for the failing
+   unit and resolve its qname:
+   - Apex class/method in the trace → `find_nodes ApexClass:<Name>` / `ApexMethod:<Name>.*`.
+   - Failing test → the test method, then its `IS_TEST_FOR` target.
+   - "Field X isn't updating" → `analyze_field` on `<Object>.<Field>`.
+   If you can't anchor it, ask the user for the class/object name — don't guess.
+
+2. **Read the failing unit.** `explain_code(qname=…)` reads stored source for Apex methods
+   (`ApexMethod:…`), trigger bodies (`ApexTrigger:…`), and Flows (`Flow:…`). For a **whole
+   class, LWC JS, or managed/`(hidden)` code the graph has no source** — fetch it: read the local
+   sfdx file (`force-app/main/default/{classes,triggers,flows}/<Name>.{cls,trigger,flow-meta.xml}`)
+   or `sf project retrieve start -m "ApexTrigger:<Name>"`. See `sf-explain-code` for the full
+   fallback. Confirm the trace's line maps to a real branch (SOQL, DML, deref).
+
+3. **Look outward for the real cause — this is where graphs beat grep:**
+   - `trace_downstream(qname)` — what it calls / reads / writes. A `System.NullPointer` or
+     `LimitException` usually originates in a callee or a SOQL/DML it triggers.
+   - `trace_upstream(qname)` — who invokes it, and with what context (trigger vs batch vs
+     LWC). Order-of-execution bugs hide here.
+   - For an object symptom: `sf-flow-impact` / `analyze_field` — every trigger, Flow,
+     Process Builder, and validation rule that fires on the object. "Trigger isn't firing"
+     and "field reverts" are almost always a competing automation.
+   - **If the cause depends on actual data** (a field's real value, a CMDT/setting the code
+     reads, a record-type/picklist value, data skew) and the graph doesn't hold it, pull it
+     from the org — config/metadata records freely (`sf data query … FROM <Type>__mdt`), live
+     business records only as a small bounded `LIMIT` sample (real/PII data — see
+     `sf-graph-router` → "When the graph doesn't hold what the analysis needs").
+   - Governor `LimitException` → hand to `sf-governor-risk-fix` scoped to the class to find
+     the SOQL/DML-in-loop.
+
+4. **Check what recently changed.** `sf-what-broke` (or `what_broke`) for the org since the
+   last deploy/ingest — if the failing node or any node it depends on changed recently,
+   that's your prime suspect. Correlate the failure's first-seen time with the change.
+
+5. **Check test coverage of the suspect path** — `test_gap_intelligence_from_git_diff` (if a
+   diff exists) or the `IS_TEST_FOR` edges — a path with no test is where regressions live.
+
+6. **State a single hypothesis, then confirm it** against the graph before recommending a
+   fix. "I think X because the graph shows Y." If the evidence doesn't support it, form a
+   new hypothesis — don't stack speculative fixes.
+
+## Staleness check
+
+If `staleness_check` is not available (the server runs with `SFGRAPH_TOOLS=core`), skip this step and say the graph's freshness was not checked.
+
+Call `staleness_check` first. A stale graph misleads root-cause analysis (the change that
+caused the bug may not be ingested yet). If stale, warn and recommend
+`sfgraph ingest --org <alias>` before trusting the upstream/recent-change steps.
+
+## Response shape
+
+- **Symptom** — the error/test/behaviour, anchored to a qname.
+- **Evidence chain** — the graph facts that narrow the cause (callers, callees, competing
+  automation, recent changes, coverage gaps), each tied to the tool that surfaced it.
+- **Root-cause hypothesis** — one, with the supporting evidence. Confidence level.
+- **Recommended fix** — described, not auto-applied; hand to `sf-architect-apex` /
+  `sf-architect-ui` / `sf-governor-risk-fix` to design it, grounded in this evidence.
+- **Mermaid** — optional: the failing path (caller → unit → callee/field) when it clarifies.
+
+## Don't
+
+- Don't propose a fix before anchoring the symptom to a real node and reading its source.
+- Don't ignore competing automation — on object symptoms it's the most common root cause and
+  the thing a stack trace alone never shows.
+- Don't stack multiple speculative fixes; one hypothesis, confirmed, at a time.
+- Don't edit code here — root-cause + evidence is the deliverable; design hands off.
+- Don't trust a stale graph for "what recently changed" without flagging it.

package/skills/sf-deployment-manifest/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sf-deployment-manifest
-description: Generate a package.xml deployment manifest covering a change set and its required dependencies.
+description: Generate package.xml and destructiveChanges.xml from the difference between two ingested orgs. The tool adds no dependencies; extra ones are added by hand with the user.
 triggers:
   - "deployment manifest"
   - "package.xml"
@@ -17,18 +17,22 @@ tools_used:
 
 Use when the user wants a `package.xml` that captures a set of changes plus everything they transitively depend on for a successful deploy.
 
+## Evidence rule — say it only if something backs it
+
+State a fact about this org or the Salesforce platform **only when evidence backs it**: a tool/graph result, source you actually read (local sfdx file or an org fetch), a live org query, or official Salesforce documentation. If you don't have that, say so plainly — "the graph doesn't show this", "unverified", "I'd need to check the org" — and either go get the evidence or stop. **Never fill the gap with a plausible-sounding guess**: an invented field/method/object name, an assumed dependency, or a governor number recalled from memory. Label each claim as **graph-confirmed** (a tool returned it), **inferred** (you reasoned it from graph facts — say which facts), or **general Salesforce knowledge**. For platform behaviour — governor limits, order of execution, sharing/FLS semantics, API rules — cite the official doc (developer.salesforce.com; fetch it if unsure) instead of asserting from memory. If the graph is stale or the org was never ingested, lead with that caveat — your grounding may be wrong.
+
 ## Playbook
 
 1. Establish the source and target orgs. The tool's contract today is a strict cross-org diff: it inputs `from_org` (source) and `to_org` (target) and emits the metadata that exists in `from_org` but is missing or different in `to_org` (plus a `destructiveChanges.xml` for things present only in `to_org`).
 2. Optionally call `cross_org_diff` first to preview the set difference before generating the manifest XML.
-3. Call `deployment_manifest_gen` with `from_org` + `to_org` (+ optional `category` filter). The tool does NOT currently walk `DEPENDS_ON` edges — it returns the set difference as `package.xml` / `destructiveChanges.xml`. Dependency-closure walking is planned future work; for now the user is responsible for any additional parent metadata not surfaced by the diff.
-4. Inspect the result for ambiguous dependencies (managed-package types, namespace mismatches) and surface them as warnings.
+3. Call `deployment_manifest_gen` with `from_org` + `to_org` (+ optional `category` filter). The tool does not walk dependency edges: it returns the set difference as `package.xml` / `destructiveChanges.xml`, and the user is responsible for any parent metadata the diff does not surface. Managed-package and standard items found in one org only are left out of both files by default and named in the report; pass `include_managed: true` / `include_standard: true` only when the user asks for them.
+4. Surface the report's notes as warnings: items left out because they have no deployment type, items hidden as managed or standard, and an incomplete comparison. Go through every `destructiveChanges.xml` member with the user before they deploy it.
 5. Emit the `package.xml` inside a fenced code block. Also emit `destructiveChanges.xml` if the diff includes removals.
 6. If extra dependencies are needed beyond the raw diff, ask the user to extend the set manually — do not silently fabricate dependency edges the graph doesn't have.
 
-## Visualization
+## Visualization (optional — you build it)
 
-Render a **`flowchart LR`** dependency closure graph. The user's explicit change set is one subgraph; auto-pulled dependencies are another. Edge labels carry the dependency reason (`parent-of`, `layout-for`, `required-permission`).
+`deployment_manifest_gen` returns only the package.xml / destructiveChanges.xml (plus an `incomplete` block flagging dropped/truncated members) — it does NOT return a diagram or walk dependency edges. If a visual helps, render a **`flowchart LR`** closure graph YOURSELF from the manifest's member list: the user's explicit change set is one subgraph; any dependencies you add manually are another. Edge labels carry the dependency reason (`parent-of`, `layout-for`, `required-permission`).
 
 ```
 flowchart LR
@@ -47,6 +51,8 @@ If the closure expands past 60 nodes, summarise per metadata type and only rende
 
 ## Staleness check
 
+If `staleness_check` is not available (the server runs with `SFGRAPH_TOOLS=core`), skip this step and say the graph's freshness was not checked.
+
 Before calling `deployment_manifest_gen`, invoke `staleness_check` for the source org. A stale graph means missing dependencies in the manifest, which fail at deploy time. If the report says stale, surface a warning to the user:
 
 > Your ingest is N days old. Run `sfgraph ingest --org <alias>` to refresh, or proceed with the understanding that the graph may not reflect recent changes.
@@ -56,11 +62,11 @@ Then continue with the playbook.
 ## Response Shape
 
 - **Source set** — what was requested.
-- **Closure additions** — what was pulled in by dependency traversal, grouped by metadata type.
+- **Manual additions** — dependencies the user chose to add (the tool adds none), grouped by metadata type.
 - **Warnings** — managed-package / namespace / ambiguous-dependency notes.
 - **package.xml** — fenced code block.
 - **destructiveChanges.xml** — fenced code block (only if applicable).
-- **Mermaid dependency graph** — embedded.
+- **Mermaid dependency graph** — optional, drawn by you (see Visualization).
 
 ## Don't
 

package/skills/sf-explain-code/SKILL.md

@@ -20,11 +20,23 @@ tools_used:
 
 Use this skill when the user wants a plain-English explanation of a specific code unit (an Apex method, an LWC handler, a trigger body). It reads the stored source via the graph's snippet store, generates an annotated explanation, and caches that explanation back so the next caller gets it for free.
 
+## Evidence rule — say it only if something backs it
+
+State a fact about this org or the Salesforce platform **only when evidence backs it**: a tool/graph result, source you actually read (local sfdx file or an org fetch), a live org query, or official Salesforce documentation. If you don't have that, say so plainly — "the graph doesn't show this", "unverified", "I'd need to check the org" — and either go get the evidence or stop. **Never fill the gap with a plausible-sounding guess**: an invented field/method/object name, an assumed dependency, or a governor number recalled from memory. Label each claim as **graph-confirmed** (a tool returned it), **inferred** (you reasoned it from graph facts — say which facts), or **general Salesforce knowledge**. For platform behaviour — governor limits, order of execution, sharing/FLS semantics, API rules — cite the official doc (developer.salesforce.com; fetch it if unsure) instead of asserting from memory. If the graph is stale or the org was never ingested, lead with that caveat — your grounding may be wrong.
+
 ## Playbook
 
-1. **Resolve the target qname.** Most users say "explain `AccountSvc.calculate`" — that maps to the qname `ApexMethod:AccountSvc.calculate(N)` where N is the arity. If the arity is unknown or the name is ambiguous, call `trace_upstream` with a partial match to enumerate candidates and confirm with the user.
+1. **Resolve the target qname.** Snippets are stored for Apex methods (`ApexMethod:AccountSvc.calculate(N)`, N = arity), Apex triggers (`ApexTrigger:AccountTrigger`) and Flows (`Flow:Lead_Router`, the Flow XML). A class qname like `ApexClass:AccountSvc` has no snippet of its own (it returns "No snippet stored"): enumerate its methods with `find_nodes(pattern="ApexMethod:AccountSvc.*")` and either pick the method the user meant or explain each in turn. For fields and objects there is no snippet: redirect to `analyze_field` / `sf-cross-layer-trace` instead. If the arity is unknown or the name is ambiguous, use `find_nodes` to enumerate candidates and confirm with the user.
 2. **`staleness_check`** for the linked org. If stale, surface a warning so the user knows the cached source may not reflect production.
 3. **`explain_code(qname=X)`** — pull the stored snippet and any prior cached explanation. The tool returns the source text in a fenced code block.
+   - **If the graph doesn't have the full source, FETCH it — don't explain from a stub.** The ingest stores source for Apex methods, Apex triggers and Flows, and **nothing for managed/`(hidden)` code**. When `explain_code` returns "No snippet stored" or an empty body, or you need a whole class, get the real source in this order:
+     1. **Local sfdx working tree** (fastest, reflects un-deployed changes) — read the file directly:
+        - Apex class → `force-app/main/default/classes/<Name>.cls`
+        - Apex trigger → `force-app/main/default/triggers/<Name>.trigger`
+        - Flow → `force-app/main/default/flows/<Name>.flow-meta.xml`
+        (the package dir may differ — check `packageDirectories` in `sfdx-project.json`).
+     2. **Retrieve from the org** when there's no local copy: `sf project retrieve start -m "ApexTrigger:<Name>"` (or `ApexClass:<Name>` / `Flow:<Name>`), then read the retrieved file. For an Apex body without a project, `sf data query --use-tooling-api -q "SELECT Body FROM ApexClass WHERE Name='<Name>'"` (or `ApexTrigger`).
+   - State which source you used (graph snippet / local file / org retrieve) so the reader knows whether it reflects production or local edits.
 4. **Generate the explanation**, structured as:
    - **One-paragraph summary**: what the method does at a high level.
    - **Annotated source block**: re-emit the source with terse `// → ...` comments after each conditional branch and each loop. Keep comments to one line.
@@ -47,6 +59,8 @@ flowchart TD
 
 ## Staleness check
 
+If `staleness_check` is not available (the server runs with `SFGRAPH_TOOLS=core`), skip this step and say the graph's freshness was not checked.
+
 Before reading the snippet, call `staleness_check` for the org. If the ingest is stale:
 
 > Your ingest is N days old. The source you're explaining may not match production. Run `sfgraph ingest --org <alias>` to refresh.
@@ -79,3 +93,4 @@ If the user says yes, hand off to `sf-find-similar` with mode=qname and the same
 - Don't write anything to Salesforce.
 - Always render the source inside a fenced code block tagged with the `sourceFormat` returned by `explain_code` (`apex`, `js`, `html`, etc.).
 - Don't fabricate behaviour — if the source is empty or stubbed, say so plainly.
+- Don't pass a class or field qname expecting source: only `ApexMethod:...(N)`, `ApexTrigger:...` and `Flow:...` have a snippet. On "No snippet stored" for a class, resolve to a method qname rather than reporting failure.

package/skills/sf-find-similar/SKILL.md

@@ -24,6 +24,10 @@ tools_used:
 
 Use this skill when the user wants discovery rather than exact lookup: *"what other Apex methods are like this one"*, *"find code that handles order cancellation"*, *"is there anything similar to `accountTile`?"*. Powered by the in-process MiniLM-L6 embeddings sfgraph produces during every ingest.
 
+## Evidence rule — say it only if something backs it
+
+State a fact about this org or the Salesforce platform **only when evidence backs it**: a tool/graph result, source you actually read (local sfdx file or an org fetch), a live org query, or official Salesforce documentation. If you don't have that, say so plainly — "the graph doesn't show this", "unverified", "I'd need to check the org" — and either go get the evidence or stop. **Never fill the gap with a plausible-sounding guess**: an invented field/method/object name, an assumed dependency, or a governor number recalled from memory. Label each claim as **graph-confirmed** (a tool returned it), **inferred** (you reasoned it from graph facts — say which facts), or **general Salesforce knowledge**. For platform behaviour — governor limits, order of execution, sharing/FLS semantics, API rules — cite the official doc (developer.salesforce.com; fetch it if unsure) instead of asserting from memory. If the graph is stale or the org was never ingested, lead with that caveat — your grounding may be wrong.
+
 ## When to choose this vs. the other tools
 
 | Question shape | Use |
@@ -80,10 +84,12 @@ xychart-beta
 
 ## Common failure modes & how to handle them
 
-- **`reason: vector_index_unavailable`** — the org's graph was ingested before embeddings were wired up, or the optional `@ryanstark24/sfgraph-models` install was skipped. Tell the user verbatim what the tool's markdown suggests: re-install with `npm install -g @ryanstark24/sfgraph` and re-ingest with `--rebuild`.
-- **`reason: no_focal_vector`** (qname mode) — the qname is wrong or its label isn't embedded. Confirm the qname spelling. If correct, suggest re-trying with `text` mode using the user's description of the node.
-- **`reason: embedder_unavailable`** (text mode) — the MiniLM runtime isn't present. Fall back to qname mode if the user can name a similar node.
-- **`reason: no_neighbours`** — genuinely no similar nodes. Suggest dropping the `label` filter, or running structural `trace_upstream` / `trace_downstream` instead.
+The report says which case applies in plain words; the reason code below is only in the tool's structured data.
+
+- **Search by meaning not set up** (`vector_index_unavailable`) — the org's graph was ingested before embeddings were wired up, or the optional `@ryanstark24/sfgraph-models` install was skipped. Tell the user verbatim what the tool's markdown suggests: re-install with `npm install -g @ryanstark24/sfgraph` and re-ingest with `--rebuild`.
+- **No stored meaning for the qname** (`no_focal_vector`, qname mode) — the qname is wrong or its label isn't embedded. Confirm the qname spelling. If correct, suggest re-trying with `text` mode using the user's description of the node.
+- **Model files missing** (`embedder_unavailable`, text mode) — the MiniLM runtime isn't present. Fall back to qname mode if the user can name a similar node.
+- **Nothing similar** (`no_neighbours`) — genuinely no similar nodes. Suggest dropping the `label` filter, or running structural `trace_upstream` / `trace_downstream` instead.
 
 ## Response shape
 

package/skills/sf-flow-impact/SKILL.md

@@ -17,6 +17,10 @@ tools_used:
 
 Use when the user asks which automation references a specific field or object — typically before a field rename, type change, or deletion.
 
+## Evidence rule — say it only if something backs it
+
+State a fact about this org or the Salesforce platform **only when evidence backs it**: a tool/graph result, source you actually read (local sfdx file or an org fetch), a live org query, or official Salesforce documentation. If you don't have that, say so plainly — "the graph doesn't show this", "unverified", "I'd need to check the org" — and either go get the evidence or stop. **Never fill the gap with a plausible-sounding guess**: an invented field/method/object name, an assumed dependency, or a governor number recalled from memory. Label each claim as **graph-confirmed** (a tool returned it), **inferred** (you reasoned it from graph facts — say which facts), or **general Salesforce knowledge**. For platform behaviour — governor limits, order of execution, sharing/FLS semantics, API rules — cite the official doc (developer.salesforce.com; fetch it if unsure) instead of asserting from memory. If the graph is stale or the org was never ingested, lead with that caveat — your grounding may be wrong.
+
 ## Playbook
 
 1. Resolve the target. Call `analyze_field` for a single field; for an SObject, list its fields first and ask the user to narrow if the scope is large.
@@ -44,6 +48,8 @@ If more than 20 flows reference the field, group leaves by entry-trigger type an
 
 ## Staleness check
 
+If `staleness_check` is not available (the server runs with `SFGRAPH_TOOLS=core`), skip this step and say the graph's freshness was not checked.
+
 Before calling `analyze_field`, invoke `staleness_check` for the target org. Newly-created or recently-modified Flows are invisible in a stale graph, which makes this skill produce false negatives. If the report says stale, surface a warning to the user:
 
 > Your ingest is N days old. Run `sfgraph ingest --org <alias>` to refresh, or proceed with the understanding that the graph may not reflect recent changes.