@raishin/vanguard-frontier-agentic 2.3.0 → 2.5.0

package/skills/salesforce/salesforce-flow-automation-review-skill/references/automation-conflict-matrix.md

@@ -0,0 +1,193 @@
+# Automation Conflict Matrix Reference
+
+Reference for understanding precedence, conflict scenarios, and interaction
+patterns between Salesforce automation layers.
+
+---
+
+## Execution Order (Single Record Save)
+
+The following is the standard Salesforce record save execution order:
+
+```
+1.  Load the original record from database (or initialize for new record)
+2.  Load new field values from the incoming request
+3.  Execute all Before-Save record-triggered Flows
+4.  Execute all Before Apex Triggers
+5.  Run system validations (page layouts, required fields, field formats)
+6.  Save to database (not yet committed)
+7.  Execute all After Apex Triggers
+8.  Execute Assignment Rules (Leads and Cases)
+9.  Execute Auto-Response Rules (Leads and Cases)
+10. Execute Workflow Rules (LEGACY - end-of-life scheduled)
+    - Field updates from workflow rules re-execute before/after triggers
+11. Execute processes (Process Builder - LEGACY - end-of-life scheduled)
+12. Execute all After-Save record-triggered Flows
+13. Execute Escalation Rules
+14. Execute Entitlement Rules
+15. Commit to database
+16. Execute post-commit logic (emails, outbound messages, async actions)
+```
+
+Workflow rule field updates cause triggers to re-fire (step 4-7 repeat). This
+is a well-known source of unexpected behavior and is one reason Salesforce is
+retiring Workflow Rules.
+
+---
+
+## Layer Comparison Matrix
+
+| Capability | Apex Trigger | Before-Save Flow | After-Save Flow | Workflow Rule | Process Builder |
+|------------|-------------|-----------------|----------------|--------------|----------------|
+| Before-save field update | Yes | Yes | No | Yes (re-fires trigger) | No |
+| After-save actions | Yes | No | Yes | Yes | Yes |
+| Create child records | Yes | No | Yes | No | Yes |
+| Cross-object update | Yes | No | Yes (via subflow) | Yes (1 hop) | Yes |
+| Callouts | Yes (future) | No | No (unless async) | No | No |
+| Complex logic (branching) | Yes | Yes | Yes | Limited | Yes (limited) |
+| Recursion guard available | Yes (static var) | Conditional | Conditional | No | No |
+| Governor limit shared | Yes | Yes | Yes | Yes | Yes |
+| Testable in unit tests | Yes | Via mock | Via mock | Limited | Limited |
+
+---
+
+## Conflict Scenario Reference
+
+### Scenario 1: Before-Save Flow vs Before Apex Trigger field conflict
+
+When both a Before-Save Flow and a Before Apex Trigger update the same field,
+the trigger executes AFTER the flow. The trigger's value wins.
+
+```
+Before-Save Flow: sets Account.Rating = 'Warm'
+Before Apex Trigger: sets Account.Rating = 'Hot'
+
+Result in database: Account.Rating = 'Hot'
+```
+
+Resolution: Decide which layer owns each field. Document ownership in metadata
+comments. If the trigger's value should not override the flow, move field
+assignment exclusively to the flow or guard the trigger logic with a field-change check.
+
+### Scenario 2: Workflow Field Update triggers re-fire of Apex Trigger
+
+Workflow Rules with field updates cause the entire before/after trigger cycle
+to re-execute. This is the primary reason to migrate Workflow Rules to Flows.
+
+```
+Apex Trigger fires on Account update
+  -> sends Platform Event (counted as one callout)
+Workflow Rule field update re-fires trigger
+  -> attempts to send Platform Event again
+  -> if trigger lacks recursion guard, second Platform Event fires
+  -> governor limit on callouts approaches
+```
+
+Resolution: Add recursion guard to trigger (see apex-anti-patterns.md). Or
+migrate workflow field updates to Before-Save Flows to eliminate re-fire.
+
+### Scenario 3: Two After-Save Flows update the same field
+
+Multiple After-Save Flows on the same object and trigger condition will both
+execute. If both update the same field, the last one to execute wins.
+
+Execution order between multiple flows is not guaranteed and may change between
+releases. Do not rely on specific ordering.
+
+Resolution: Consolidate flows that modify the same field into one flow with
+Decision elements to handle the branching logic.
+
+### Scenario 4: Flow creates a record, Apex Trigger fires on creation
+
+An After-Save Flow on Contact creates a related Task. The Task creation fires
+the Task Apex Trigger. If the Task trigger updates the Contact, it can create
+a loop.
+
+```
+Contact saved
+  -> Contact After-Save Flow: Create Task
+     -> Task Apex Trigger fires: updates Contact (sets ContactTaskCount__c++)
+        -> Contact After-Save Flow fires again: creates another Task...
+           RECURSION
+```
+
+Resolution:
+- Add a trigger condition to the Contact flow: only fire if the triggering
+  field (not ContactTaskCount__c) changed.
+- Add a recursion guard in the Task trigger handler.
+
+### Scenario 5: Validation Rule vs Before-Save Flow ordering
+
+Validation Rules execute after Before-Save Flows but before database commit.
+If a Before-Save Flow sets a field value that a Validation Rule then checks,
+the updated value is visible to the Validation Rule.
+
+```
+Before-Save Flow: sets Status__c = 'Closed'
+Validation Rule: ERROR IF Status__c = 'Closed' AND CloseDate__c = null
+  -> Will fire and block save if CloseDate__c is null
+```
+
+This interaction is intentional and correct behavior. Document it in the
+Validation Rule's description.
+
+### Scenario 6: Assignment Rules vs After-Save Flow ownership
+
+Case Assignment Rules run before After-Save Flows. If an After-Save Flow also
+sets the OwnerId of a Case, the flow's OwnerId will overwrite the assignment
+rule's OwnerId.
+
+Resolution: Choose one authoritative ownership assignment mechanism. If
+assignment rules are the authority, the flow must not touch OwnerId.
+
+---
+
+## Detecting Automation Conflicts
+
+### CLI: List active automations on an object
+
+```bash
+# List all active Flows on Account
+sf data query \
+  --query "SELECT Label, ApiName, Status, TriggerType \
+           FROM FlowDefinition \
+           WHERE TriggerType IN ('RecordBeforeSave','RecordAfterSave') \
+           AND Status = 'Active'" \
+  --use-tooling-api \
+  -o my-org
+
+# List active Apex Triggers on Account
+sf data query \
+  --query "SELECT Name, Status, TableEnumOrId \
+           FROM ApexTrigger \
+           WHERE TableEnumOrId = 'Account' AND Status = 'Active'" \
+  --use-tooling-api \
+  -o my-org
+```
+
+### Conflict Analysis Checklist
+
+- [ ] Identify all active automations (flows, triggers, workflow rules, processes)
+  on the object being modified.
+- [ ] Map which fields each automation reads and writes.
+- [ ] Flag any field written by more than one automation layer (potential conflict).
+- [ ] Identify any cross-object updates that could trigger secondary automations
+  on related objects.
+- [ ] Verify recursion guards exist for any automation that updates the same
+  object or a related object that feeds back.
+
+---
+
+## Migration Status Reference
+
+
+| Legacy Technology | Replacement | Salesforce Guidance |
+|-------------------|------------|---------------------|
+| Workflow Rules | Record-Triggered Flow | Retire by migration |
+| Process Builder | Record-Triggered Flow | Retire by migration |
+| Workflow Outbound Messages | Platform Events / Flow HTTP Callout | Migrate proactively |
+| Approval Processes | Approval Processes (retained) | No migration needed |
+
+Salesforce has announced retirement of Workflow Rules and Process Builder.
+Check the official retirement timeline before using these in new development
+or when assessing risk in existing orgs.

package/skills/salesforce/salesforce-flow-automation-review-skill/references/fault-path-design.md

@@ -0,0 +1,189 @@
+# Fault Path Design Reference
+
+Patterns for handling errors in Salesforce Flows with resilient fault paths,
+escalation logic, and retry strategies.
+
+---
+
+## Why Fault Paths Are Required
+
+Every Flow element that can fail — Create/Update/Delete Records, Apex Actions,
+HTTP Callout Actions, Send Email elements — has a Fault connector in Flow
+Builder. If no Fault connector is attached, an unhandled fault terminates the
+flow with a generic error page and an email to the running user's org
+admin. No audit record is created.
+
+Required fault paths on:
+- All DML elements (Create, Update, Delete, Upsert Records)
+- All Apex Action elements
+- All HTTP Callout actions (Salesforce Flow with External Services / MuleSoft)
+- Send Email / Send Custom Notification
+- Subflow elements
+
+---
+
+## Fault Path Levels
+
+### Level 1: Minimum Viable Fault Path
+
+Log the error, show a user-friendly message, do not leave the user on a broken screen.
+
+```
+DML Element: Create Records (Case)
+  Fault Connector ->
+    Assignment: errorMessage = {!$Flow.FaultMessage}
+    Screen: "We couldn't complete your request. Please contact support."
+            (show errorMessage in a non-technical format)
+```
+
+### Level 2: Fault Logging to Custom Object
+
+Persist fault details for later diagnosis without developer log access.
+
+```apex
+// Custom object: FlowErrorLog__c
+// Fields: FlowName__c, FaultMessage__c, RecordId__c, RunningUserId__c, Timestamp__c
+```
+
+Flow configuration:
+```
+Fault Connector ->
+  Assignment: Set variables
+    flowErrorName = "Case Creation Flow"
+    faultMsg = {!$Flow.FaultMessage}
+    faultUserId = {!$User.Id}
+    faultTimestamp = {!$Flow.CurrentDateTime}
+  Create Records: FlowErrorLog__c
+    FlowName__c = {!flowErrorName}
+    FaultMessage__c = {!faultMsg}
+    RunningUserId__c = {!faultUserId}
+    Timestamp__c = {!faultTimestamp}
+  Screen: User-friendly error message
+```
+
+### Level 3: Escalation Flow
+
+For critical business processes, route the failed transaction to a human queue.
+
+```
+Fault Connector ->
+  Assignment: Set error variables
+  Create Records: FlowErrorLog__c (persist fault)
+  Create Records: Case
+    Subject = "Automation Failure: {!flowErrorName}"
+    Description = {!$Flow.FaultMessage}
+    OwnerId = [Error_Handling_Queue Id]
+    Priority = High
+  Send Notification: Alert on-call team via Custom Notification
+  Screen: "Your request has been escalated to our support team (Ticket: {!caseNumber})."
+```
+
+### Level 4: Retry Pattern (Platform Event-based)
+
+For transient failures (network timeouts, external API 503), retry without
+blocking the user.
+
+```
+Fault Connector ->
+  Decision: Is this a retryable error?
+    YES (fault message contains "timeout" or "503") ->
+      Create Records: RetryQueue__e (Platform Event)
+        FlowName__c = "Case Creation Flow"
+        InputData__c = JSON.serialize(inputVariables)
+        AttemptNumber__c = {!currentAttempt}
+      Screen: "We're processing your request. You'll receive a notification when complete."
+    NO ->
+      Create Records: FlowErrorLog__c
+      Screen: "Unrecoverable error. Please contact support."
+```
+
+A Platform Event-triggered flow or Apex subscriber processes the RetryQueue event
+with exponential backoff.
+
+---
+
+## Retry Backoff Strategy
+
+```apex
+// Apex implementation of exponential backoff for Flow-invoked callouts
+public class RetryableCalloutHandler implements Queueable, Database.AllowsCallouts {
+    private Integer attemptNumber;
+    private String payload;
+    private String endpoint;
+    private Integer maxAttempts = 5;
+
+    public void execute(QueueableContext ctx) {
+        try {
+            HttpRequest req = new HttpRequest;
+            req.setEndpoint(endpoint);
+            req.setMethod('POST');
+            req.setBody(payload);
+            req.setTimeout(30000);
+            HttpResponse res = new Http.send(req);
+
+            if (res.getStatusCode >= 500) {
+                throw new CalloutException('Server error: ' + res.getStatusCode);
+            }
+            // Success: process response
+        } catch (Exception e) {
+            attemptNumber++;
+            if (attemptNumber < maxAttempts) {
+                // Backoff: 2^attemptNumber * 1000ms (via Platform Event delay)
+                // Enqueue next retry (Queueable cannot sleep, use Scheduled Apex or PE)
+                System.enqueueJob(new RetryableCalloutHandler(
+                    attemptNumber, payload, endpoint, maxAttempts
+                ));
+            } else {
+                // Max retries reached - log and alert
+                insert new FlowErrorLog__c(
+                    FlowName__c = 'RetryableCallout',
+                    FaultMessage__c = 'Max retries reached: ' + e.getMessage,
+                    Timestamp__c = DateTime.now
+                );
+            }
+        }
+    }
+}
+```
+
+Backoff schedule:
+| Attempt | Wait Before Retry |
+|---------|------------------|
+| 1 | 2 seconds |
+| 2 | 4 seconds |
+| 3 | 8 seconds |
+| 4 | 16 seconds |
+| 5 | Fail permanently |
+
+---
+
+## Fault Message Parsing
+
+`{!$Flow.FaultMessage}` contains the Salesforce error string. Parse common
+patterns to determine error category:
+
+| Fault Message Pattern | Category | Recommended Action |
+|----------------------|----------|-------------------|
+| `UNABLE_TO_LOCK_ROW` | Database lock contention | Retry after backoff |
+| `FIELD_CUSTOM_VALIDATION_EXCEPTION` | Validation rule fired | Do not retry; show validation message to user |
+| `INSUFFICIENT_ACCESS` | Sharing/FLS violation | Do not retry; escalate to admin |
+| `DUPLICATE_VALUE` | Duplicate rule fired | Do not retry; show duplicate management UI |
+| `REQUEST_RUNNING_TOO_LONG` | CPU timeout | Break into smaller batches |
+| `System.CalloutException` | Network issue | Retry with backoff |
+| `FIELD_INTEGRITY_EXCEPTION` | Foreign key violation | Check lookup target exists |
+
+---
+
+## Fault Path Design Checklist
+
+- [ ] Every DML element has a Fault connector.
+- [ ] Every Apex Action element has a Fault connector.
+- [ ] Every External Service / HTTP Callout element has a Fault connector.
+- [ ] Fault paths log `{!$Flow.FaultMessage}` to a persistent store (not just `System.debug`).
+- [ ] Fault paths for screen flows show a user-friendly message (not raw error text).
+- [ ] Fault paths for autolaunched flows create an error log record and/or send
+  a notification to an operations team.
+- [ ] Critical process fault paths create a support case or alert ticket.
+- [ ] Transient error types trigger a retry mechanism; permanent errors are logged.
+- [ ] Fault handling does not itself perform DML that could fail (double-fault
+  scenario creates silent failure).

package/skills/salesforce/salesforce-flow-automation-review-skill/references/flow-anti-patterns.md

@@ -0,0 +1,211 @@
+# Flow Anti-Patterns Reference
+
+Common mistakes in Salesforce Flow
+configurations that cause
+performance failures, infinite recursion, data integrity issues, or
+unhandled errors.
+
+---
+
+## 1. DML in a Loop Element
+
+### Description
+Using a "Create Records", "Update Records", or "Delete Records" element inside
+a Loop element causes one DML operation per iteration — equivalent to DML in an
+Apex loop.
+
+### Why It Fails
+Flows share Apex governor limits when invoked from a trigger context. A loop
+over 200 records with an Update Records inside exceeds the DML statement limit.
+
+### Detection
+In Flow Builder: navigate to each Loop element and inspect elements inside the
+loop body. Any Create/Update/Delete Records element is a finding.
+
+### Correct Pattern
+
+Move DML outside the loop:
+1. Inside the loop, use an Assignment element to build a collection variable
+   (`recordCollection`).
+2. After the loop ends, use a single Update Records / Create Records element
+   operating on the full collection.
+
+```
+Loop (iterate over accountList)
+  -> Assignment: add account to toUpdateCollection (use "Add" operation)
+End Loop
+-> Update Records: Source = toUpdateCollection (one DML statement for all)
+```
+
+---
+
+## 2. Missing Fault Paths
+
+### Description
+A Flow with callout actions, DML actions, or Apex actions has no Fault connector
+from those elements. If the action fails, the flow terminates with an unhandled
+fault — often surfaced to the user as a generic error page.
+
+### Why It Matters
+Silent failures in critical business processes (case creation, order submission)
+create data integrity gaps that are hard to diagnose.
+
+### Detection
+In Flow Builder: click each Action, Create Records, Update Records, or Delete
+Records element. Look for a red Fault connector (anchor at bottom of element).
+If no Fault connector exists, that element has no fault handling.
+
+### Correct Pattern
+
+```
+Create Records: Case
+  Success path -> next element
+  Fault path -> Fault Connector
+    -> Assignment: set errorMessage = {!$Flow.FaultMessage}
+    -> Create Records: Log Error (CustomErrorLog__c object)
+    -> Screen (or Subflow): "Something went wrong. Your request ID: {!caseId}"
+```
+
+Minimum viable fault handling:
+- Log the fault message to a custom error log object.
+- Show a user-friendly message rather than a raw error.
+- For autolaunched flows triggered from Apex: throw a re-throw-able exception
+  so the Apex caller can handle it.
+
+---
+
+## 3. Infinite Recursion
+
+### Description
+A record-triggered flow updates the same record it was triggered on (or updates
+a related record that triggers another flow that updates the original record),
+creating a loop until Salesforce detects recursion and throws an error.
+
+### Why It Happens
+Flows triggered on Account > After Save that update an Account field will
+re-trigger the same flow. Without a guard condition, this recurses.
+
+### Detection
+For each record-triggered flow:
+1. Check the trigger object.
+2. Check all Update Records or Create Records elements.
+3. If any element updates a record of the same object type as the trigger, check
+   whether the update will re-satisfy the trigger condition.
+
+### Correct Patterns
+
+**Pattern A: Entry condition guards**
+Add a trigger condition that only fires when the relevant field has actually changed:
+```
+Trigger Conditions:
+  Field: Status__c    Operator: Is Changed    Value: True
+  (only runs when Status__c changes, not on every save)
+```
+
+**Pattern B: Timestamp / flag field guard**
+```
+Update Records: Account
+  Set LastFlowProcessed__c = {!$Flow.CurrentDateTime}
+
+Entry Condition:
+  LastFlowProcessed__c < {!$Flow.CurrentDateTime} - 60 seconds
+  (skip if flow already ran in the last minute for this record)
+```
+
+**Pattern C: Apex-managed recursion guard**
+If flow invokes Apex, use a static boolean in the handler class (see Apex
+recursion guard pattern in apex-anti-patterns.md).
+
+---
+
+## 4. System Context vs User Context Confusion
+
+### Description
+Autolaunched Flows and Before-Save Flows run in System Context by default —
+they bypass sharing rules and FLS. This can expose records to flows that should
+not be able to see or modify them.
+
+### Execution Context Quick Reference
+
+| Flow Type | Default Context | Override Available |
+|-----------|---------------|-------------------|
+| Autolaunched Flow (no trigger) | System w/ Sharing OFF | Set "Run as" to System with Sharing or User |
+| Record-Triggered Flow (Before Save) | System w/ Sharing | Cannot change |
+| Record-Triggered Flow (After Save) | System w/ Sharing | Cannot change |
+| Screen Flow (launched by user) | User Context | Can switch to System |
+| Scheduled-Triggered Flow | System w/ Sharing OFF | Cannot change |
+| Platform Event-Triggered Flow | System w/ Sharing OFF | Cannot change |
+
+"Run as" context options may vary by API version and
+Salesforce release.
+
+### Risk Scenarios
+
+1. Autolaunched Flow queries ALL records of an object regardless of sharing, then
+   exposes results in a screen or action — data over-exposure.
+2. Before-Save Flow updates a field on a restricted object without checking
+   whether the running user should have edit access — implicit privilege escalation.
+
+### Remediation
+- For autolaunched flows that handle user data, set the Run As context to
+  "System Context With Sharing" or invoke from Apex using `with sharing`.
+- For flows that must run in system context, document the business justification
+  and restrict the flow's invocation to trusted Apex classes only.
+
+---
+
+## 5. Unguarded Get Records (No Result Check)
+
+### Description
+A Get Records element queries for a record but has no Decision element to
+check whether the record was found before using its fields downstream. If the
+record does not exist, downstream elements that reference `{!GetRecord}` will
+use null values, causing unexpected behavior or errors.
+
+### Correct Pattern
+
+```
+Get Records: Account (WHERE Id = {!recordId})
+-> Decision: Did We Find Account?
+    YES (Is Null check: {!GetAccount} Is Null = False) -> proceed with account fields
+    NO  (otherwise) -> Screen: "Account not found" or Fault logging path
+```
+
+---
+
+## 6. Hard-Coded API Names
+
+### Description
+Flow elements reference picklist values, queue names, or record type API names
+as hard-coded string literals. When these values change in production, the flow
+breaks silently.
+
+### Detection
+Search Flow XML for string literals in Assignment/Decision elements:
+```bash
+grep -rn "Status = 'Active'" force-app/main/default/flows/*.flow-meta.xml
+grep -rn "Queue\.Name" force-app/main/default/flows/*.flow-meta.xml
+```
+
+### Correct Approach
+- Use Picklist field values via `{!$GlobalConstant.EmptyString}` or via Get
+  Records to dynamically resolve names.
+- Reference Queue IDs dynamically via Get Records on Group object:
+  ```
+  Get Records: Group WHERE Name = 'Support Queue' AND Type = Queue
+  -> use {!GetQueue.Id} as OwnerId
+  ```
+
+---
+
+## Flow Anti-Pattern Summary
+
+| Anti-Pattern | Impact | PMD/Equivalent Rule |
+|-------------|--------|---------------------|
+| DML in loop | Governor limit failure | `FlowDmlInLoop` |
+| Missing fault path | Silent failures | `FlowMissingFaultPath` |
+| Infinite recursion | Recursion error | Manual review + entry conditions |
+| System context over-exposure | Data security | Architecture review |
+| Unguarded Get Records | Null field errors | `FlowUnusedVariable` (indirect) |
+| Hard-coded API names | Brittleness | Code review checklist |
+| Unactivated flow left in prod | Confusion / accidental activation | `FlowInactiveFlow` |