@ryanstark24/sfgraph-skills 1.1.4 → 1.2.0

package/dist/__tests__/installer.test.js

@@ -11,11 +11,11 @@ afterEach(() => {
     rmSync(home, { recursive: true, force: true });
 });
 describe("skills installer", () => {
-    it("installs all 16 skills to the claude target", async () => {
+    it("installs all 20 skills to the claude target", async () => {
         const results = await install("claude", { homeOverride: home });
         const skillNames = await listSkillsBundled();
-        expect(skillNames.length).toBe(16);
-        expect(results.length).toBe(16);
+        expect(skillNames.length).toBe(20);
+        expect(results.length).toBe(20);
         for (const r of results) {
             expect(r.target).toBe("claude");
             expect(r.action).toBe("created");
@@ -26,11 +26,11 @@ describe("skills installer", () => {
     });
     it("installs to the cursor target as .mdc files in Cursor's frontmatter shape", async () => {
         const results = await install("cursor", { homeOverride: home });
-        expect(results.length).toBe(16);
+        expect(results.length).toBe(20);
         const cursorDir = join(home, ".cursor", "rules");
         const files = readdirSync(cursorDir);
         expect(files.every((f) => f.endsWith(".mdc"))).toBe(true);
-        expect(files.length).toBe(16);
+        expect(files.length).toBe(20);
         // Cursor-shaped frontmatter (the three keys Cursor's rule loader reads).
         const sample = readFileSync(join(cursorDir, files[0] ?? ""), "utf8");
         expect(sample).toMatch(/^description:/m);
@@ -48,9 +48,9 @@ describe("skills installer", () => {
         const claudeCount = results.filter((r) => r.target === "claude").length;
         const cursorCount = results.filter((r) => r.target === "cursor").length;
         const vscodeCount = results.filter((r) => r.target === "vscode").length;
-        expect(claudeCount).toBe(16);
-        expect(cursorCount).toBe(16);
-        expect(vscodeCount).toBe(16);
+        expect(claudeCount).toBe(20);
+        expect(cursorCount).toBe(20);
+        expect(vscodeCount).toBe(20);
         expect(existsSync(join(home, ".claude", "skills"))).toBe(true);
         expect(existsSync(join(home, ".cursor", "rules"))).toBe(true);
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryanstark24/sfgraph-skills",
-  "version": "1.1.4",
+  "version": "1.2.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

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

@@ -65,6 +65,10 @@ 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
 
 Before calling `cross_layer_flow_map`, invoke `staleness_check` for the target org. If the report says stale, surface a warning to the user:

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

@@ -21,7 +21,7 @@ Use when the user wants to inventory metadata that appears unreferenced. Output
 
 ## 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.).
+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`, `stale_freshness`).
 2. Call `freshness_report` to layer last-touched timestamps onto each candidate. Stale + unreferenced is stronger evidence than unreferenced alone.
 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:

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

@@ -0,0 +1,103 @@
+---
+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>
+
+## 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` on the method to read the offending source.
+   - `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` scoped to the class to pinpoint the SOQL/DML-in-loop **source line** the log proved is hot.
+   - 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,96 @@
+---
+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.
+
+## 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=<ApexMethod>)` — get the source + branch
+   annotation. Confirm the line in the trace 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.
+   - 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
+
+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-explain-code/SKILL.md

@@ -22,7 +22,7 @@ Use this skill when the user wants a plain-English explanation of a specific cod
 
 ## 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 — it must be METHOD-level.** Snippets are stored only for Apex methods, so `explain_code` needs `ApexMethod:AccountSvc.calculate(N)` (N = arity), **not** a class qname like `ApexClass:AccountSvc` (that returns "No snippet stored"). If the user names a class, first enumerate its methods with `find_nodes(pattern="ApexMethod:AccountSvc.*")` and either pick the method they meant or explain each in turn. For declarative metadata (fields, objects, Flows) 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.
 4. **Generate the explanation**, structured as:
@@ -79,3 +79,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/trigger/field qname expecting source — only `ApexMethod:...(N)` has a snippet. On "No snippet stored", resolve to a method qname rather than reporting failure.

package/skills/sf-governor-risk-fix/SKILL.md

@@ -17,11 +17,32 @@ tools_used:
 
 Use when the user wants to find Apex code that risks hitting governor limits at scale. The skill produces a prioritised remediation checklist; it never rewrites Apex automatically.
 
+## What the tool actually emits
+
+`governor_risk_check` reports only the risk types the analyzer can prove from
+the graph. As of the edge-based detector these are:
+
+- **`soql_in_loop`** — a SOQL query whose `EXECUTES_SOQL` edge is tagged
+  `inLoop` (AST-verified: the query sits inside a for/while/do-while body).
+- **`dml_in_loop`** — same, for DML statements.
+- **`no_bulk`** — a trigger that doesn't iterate `Trigger.new` (body-scan path).
+
+Do **not** promise `UNBOUNDED_QUERY`, `NON_SELECTIVE_QUERY`, `CALLOUT_IN_LOOP`,
+`LARGE_HEAP`, or `RECURSIVE_TRIGGER` — the tool does not produce them. (Unbounded-
+query was removed: on a real org ~100% of SOQL has no WHERE/LIMIT in the captured
+query head, so it was pure noise.)
+
+**Live-ingest prerequisite:** `inLoop` tagging comes from the Apex AST parser. A
+graph ingested before that parser change has zero `inLoop` edges, so the check
+returns nothing. If `governor_risk_check` returns empty on an org you believe has
+in-loop SOQL, the fix is a re-ingest (`sfgraph ingest --org <alias> --rebuild`),
+not "the org is clean" — say so explicitly rather than reporting a false all-clear.
+
 ## Playbook
 
-1. Call `governor_risk_check` over the requested scope (single class, namespace, or full org). The tool returns risk records with rule id (`SOQL_IN_LOOP`, `DML_IN_LOOP`, `UNBOUNDED_QUERY`, `NON_SELECTIVE_QUERY`, `CALLOUT_IN_LOOP`, `LARGE_HEAP`, `RECURSIVE_TRIGGER`), location (class + method + line), and severity.
-2. Group findings by rule id; within each group, sort by call-site fan-in (more callers = higher blast radius).
-3. For each finding, describe the canonical fix pattern (e.g. "extract the SOQL above the loop and key the result by `Id`") in one or two sentences — do not write the code.
+1. Call `governor_risk_check` over the requested scope (single class, namespace, or full org). The tool returns risk records keyed on the **method** qname (`ApexMethod:Class.method(n)`) with `risk_type` (`soql_in_loop` / `dml_in_loop` / `no_bulk`) and evidence (the query text or DML target).
+2. Group findings by `risk_type`; within each group, sort by call-site fan-in (more callers = higher blast radius). Use `trace_upstream` on the owning class to get fan-in.
+3. For each finding, describe the canonical fix pattern (e.g. "extract the SOQL above the loop and key the result by `Id`") in one or two sentences — do not write the code. To actually design the bulkified fix, hand off to **`sf-architect-apex`** (or **`sf-architect-performance`** for LDV/query-plan work) with these call sites as grounding, so the rewrite respects the org's real selectors and trigger framework rather than a generic template.
 4. Render the Mermaid heat-map (class-by-rule) from the tool response.
 5. Produce a checklist the user can copy into a ticket: `- [ ] ClassName.methodName:line — rule — recommended pattern`.
 6. Recommend `sf-impact-from-diff` after the user applies fixes, to verify nothing downstream regressed.
@@ -60,5 +81,6 @@ Then continue with the playbook.
 
 - **Never auto-apply fixes.** This skill does not edit Apex.
 - Do not flatten severities — the bucket ordering matters.
-- Do not invent additional rules; only report what `governor_risk_check` returns.
+- Do not invent additional rules; only report what `governor_risk_check` returns (`soql_in_loop`, `dml_in_loop`, `no_bulk`).
+- Do not report "no governor risks" without first checking staleness — an empty result on a pre-AST-parser ingest means the graph lacks `inLoop` tags, not that the code is clean. Recommend a re-ingest.
 - Do not silently exclude managed-package code; mention it was filtered out if so.

package/skills/sf-graph-router/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: sf-graph-router
+description: Start here for ANY Salesforce development, design, or debugging task on an org sfgraph has ingested. Routes intent to the right sfgraph skill + MCP tool, and enforces the grounding-first rule — query the org graph for real schema / dependencies / security / governor facts BEFORE generating or changing Apex, LWC, Flow, or config. Use when the user asks to build, design, refactor, review, or debug Salesforce metadata and you are unsure which skill or tool applies, or when about to write Salesforce code from memory.
+triggers:
+  - "help me build"
+  - "design a"
+  - "write a trigger"
+  - "write apex"
+  - "create an LWC"
+  - "refactor this"
+  - "review my"
+  - "is this safe to deploy"
+  - "which sfgraph tool"
+  - "where do I start"
+  - "debug this"
+  - "why is this failing"
+tools_used:
+  - find_nodes
+  - analyze_field
+  - find_similar
+  - staleness_check
+---
+
+# sf-graph-router — start here
+
+sfgraph has a **local, queryable graph of the real org** (every Apex class, LWC, Flow,
+field, profile, Vlocity/OmniStudio component, and the edges between them). That graph is
+the antidote to the #1 failure of LLM-assisted Salesforce work: **hallucinating field
+names, classes, and call chains that don't exist in this org.** This skill decides which
+specialised skill/tool to use, and enforces one rule above all.
+
+## The grounding-first rule (non-negotiable)
+
+**Before you generate or modify any Salesforce metadata — Apex, LWC, Flow, validation
+rule, permission set — query the graph to ground yourself in what the org actually
+contains.** Designing from training data alone is how you invent `Account.Tier__c` when
+the org has `Account.Customer_Tier__c`, call a method arity that doesn't exist, or write a
+trigger that ignores the three triggers already on the object.
+
+Minimum grounding before writing code that touches object/field `X` or class `Y`:
+
+1. `find_nodes` — confirm the qnames exist (`CustomField:Account.*`, `ApexClass:*Order*`).
+2. `analyze_field` — for any field you'll read/write: who already reads/writes it, its type.
+3. `find_similar` — is there existing code that already does this? Reuse beats regenerate.
+4. For changes to existing Apex: `trace_upstream` (callers / blast radius) + `explain_code`.
+
+If `staleness_check` says the ingest is old, say so — your grounding may be out of date —
+and recommend `sfgraph ingest --org <alias>`. If the org isn't ingested at all, say the
+grounding step is unavailable and proceed with explicit low-confidence caveats.
+
+Only after grounding do you hand off to a design/knowledge skill (`sf-architect-*`) to
+write the code. Ground → design → verify. Never design → hope.
+
+## Route by intent
+
+### DEVELOPMENT — writing or changing code
+| Intent | Ground with | Then design with |
+|---|---|---|
+| "Write/extend Apex on `<Object>`" | `sf-schema-overview` (`<Object>`) + `find_nodes ApexClass:*<Object>*` + `find_similar` | `sf-architect-apex` |
+| "Build an LWC for `<feature>`" | `find_similar` (existing LWCs) + `analyze_field` (bound fields) | `sf-architect-ui` |
+| "Add an integration / callout" | `find_nodes NamedCredential:*` + `find_similar` | `sf-architect-integrations` |
+| "Reuse — is this already built?" | `sf-find-similar` (free-text concept mode) | — |
+| "Explain this method/class" | `sf-explain-code` (needs `ApexMethod:Class.m(n)`) | — |
+
+### DESIGN — architecture & data model
+| Intent | Skill |
+|---|---|
+| "Show the data model / ERD for `<Object>`" | `sf-schema-overview` |
+| "Trace `<field/LWC/method>` UI → DB" | `sf-cross-layer-trace` |
+| "Where is `<field>` used / what writes it" | `sf-flow-impact` (Flow/automation) or `analyze_field` (all layers) |
+| "Find duplicate / similar logic to consolidate" | `sf-find-similar` |
+
+### DEBUGGING — something is wrong
+| Intent | Skill |
+|---|---|
+| "This Apex/test fails / this error — why" | `sf-debug-root-cause` |
+| "Read/interpret this debug log / stack trace / 'Too many SOQL' / CPU-time log" | `sf-debug-log-analysis` |
+| "What broke after the last deploy" | `sf-what-broke` |
+| "Will my uncommitted change break anything" | `sf-wip-impact` |
+| "Blast radius + test gaps of this PR/branch" | `sf-impact-from-diff` |
+| "Compare two points in time / snapshots" | `sf-snapshot-compare` |
+
+### QUALITY / GOVERNANCE — review before ship
+| Intent | Skill |
+|---|---|
+| "Governor-limit risks (SOQL/DML in loops)" | `sf-governor-risk-fix` |
+| "FLS / sharing / who-has-access audit" | `sf-security-audit` |
+| "What's unused / safe to delete" | `sf-dead-code-audit` |
+| "Generate a deployment manifest" | `sf-deployment-manifest` |
+| "Diff two orgs (sandbox vs prod)" | `sf-cross-org-diff` |
+| "Vlocity ↔ OmniStudio migration inventory" | `sf-omnistudio-migration-audit` |
+| "Is the graph fresh / how do I refresh" | `sf-metadata-refresh` |
+| "Show me the graph visually" | `sf-web-explorer` |
+
+## Disambiguation (commonly confused)
+- **Committed vs uncommitted vs post-deploy change analysis:** PR/branch/commit → `sf-impact-from-diff`; uncommitted working tree → `sf-wip-impact`; already deployed, something regressed → `sf-what-broke`.
+- **Two orgs vs two snapshots vs one org over time:** different orgs → `sf-cross-org-diff`; named snapshots of one org → `sf-snapshot-compare`; "since last deploy" → `sf-what-broke`.
+- **Explain one unit vs trace across layers:** plain-English of one method → `sf-explain-code`; full UI→DB chain → `sf-cross-layer-trace`.
+
+## Don't
+- Don't generate Salesforce code before grounding when the org is ingested — that's the whole point of the graph.
+- Don't re-implement the routing logic in prose every turn; pick the skill and go.
+- Don't block on grounding if the org isn't ingested — degrade gracefully with a stated caveat.
+- Don't treat this skill as a destination; it hands off. Its job is selection + the grounding rule.

package/skills/sf-security-audit/SKILL.md

@@ -20,8 +20,10 @@ Use when the user asks about who can read or write a field/object, what sharing
 
 ## Playbook
 
-1. Resolve the target. Call `analyze_field` if the user gave `SObject.Field`; otherwise treat as SObject-level.
-2. Call `security_audit` with the resolved target. Capture profiles, permission sets, permission set groups, sharing rules (criteria + owner-based), OWD, and any `without sharing` Apex that touches the field.
+1. Resolve the target. Call `analyze_field` if the user gave `SObject.Field`; otherwise treat as SObject-level. `analyze_field` takes **separate `object` and `field`** params (not a single `Account.Status` string) — split before calling.
+2. Call `security_audit` with the resolved target (`object` / `field` to narrow; whole-org if neither). Capture full-access sharing rules and the FLS gap list.
+   - **FLS gaps are pre-filtered** to FLS-relevant fields: Custom Metadata Type (`__mdt`), platform-event (`__e`), big-object (`__b`), and standard system/audit fields (Id, CreatedById, SystemModstamp, …) are excluded as noise. The response notes `+N CMDT/system fields hidden`. Only pass `include_non_fls_fields: true` if the user explicitly wants that raw set — never lead with it.
+   - The inline gap list is capped (`limit`, default 30). Narrow with `object`, or raise `limit`, rather than dumping thousands of rows.
 3. Build the access matrix: Profile/PSet -> Read / Edit / Delete / View All / Modify All.
 4. Identify sharing exposure: OWD setting, sharing rules expanding access, role-hierarchy inheritance toggles.
 5. Flag risks: `without sharing` Apex selectors, missing `stripInaccessible` / `WITH SECURITY_ENFORCED`, guest user access, Experience Cloud profile reach.