@salesforce/afv-skills 1.8.0 → 1.9.0

package/skills/debugging-apex-logs/assets/dml-in-loop-fix.cls

@@ -0,0 +1,219 @@
+/**
+ * DML IN LOOP FIX PATTERN
+ *
+ * Problem: DML operations inside loops consume governor limits rapidly
+ * Detection: DEBUG LOG shows repeated DML_BEGIN entries
+ * Limits:
+ *   - 150 DML statements per transaction
+ *   - 10,000 DML rows per transaction
+ *
+ * This template demonstrates the collection pattern to fix DML in loops.
+ */
+
+// ═══════════════════════════════════════════════════════════════════════════
+// BEFORE: DML IN LOOP (PROBLEMATIC)
+// ═══════════════════════════════════════════════════════════════════════════
+
+public class ContactService_BEFORE {
+
+    // This method will fail if accounts.size() > 150
+    public void createContactsForAccounts(List<Account> accounts) {
+        for (Account acc : accounts) {
+            // DML inside loop - each iteration uses 1 DML statement
+            Contact c = new Contact(
+                FirstName = 'Primary',
+                LastName = 'Contact',
+                AccountId = acc.Id,
+                Email = acc.Name.replaceAll(' ', '') + '@example.com'
+            );
+            insert c;  // DML in loop!
+        }
+    }
+
+    // Updates in loop - also problematic
+    public void updateAccountStatuses(List<Account> accounts, String newStatus) {
+        for (Account acc : accounts) {
+            acc.Status__c = newStatus;
+            update acc;  // DML in loop!
+        }
+    }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// AFTER: COLLECTION PATTERN (CORRECT)
+// ═══════════════════════════════════════════════════════════════════════════
+
+public class ContactService_AFTER {
+
+    // This method uses only 1 DML statement regardless of accounts.size()
+    public void createContactsForAccounts(List<Account> accounts) {
+        // Step 1: Build list of records to insert
+        List<Contact> contactsToInsert = new List<Contact>();
+
+        for (Account acc : accounts) {
+            Contact c = new Contact(
+                FirstName = 'Primary',
+                LastName = 'Contact',
+                AccountId = acc.Id,
+                Email = acc.Name.replaceAll(' ', '') + '@example.com'
+            );
+            contactsToInsert.add(c);  // Add to list, no DML
+        }
+
+        // Step 2: Single DML statement AFTER the loop
+        if (!contactsToInsert.isEmpty()) {
+            insert contactsToInsert;
+        }
+    }
+
+    // Updates outside loop - correct pattern
+    public void updateAccountStatuses(List<Account> accounts, String newStatus) {
+        // Modify in loop (no DML)
+        for (Account acc : accounts) {
+            acc.Status__c = newStatus;
+        }
+
+        // Single DML after loop
+        if (!accounts.isEmpty()) {
+            update accounts;
+        }
+    }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// ADVANCED: MIXED INSERT/UPDATE/DELETE PATTERN
+// ═══════════════════════════════════════════════════════════════════════════
+
+public class RecordProcessor_Bulkified {
+
+    /**
+     * Process records with conditional insert/update/delete
+     * Uses collections for all DML operations
+     */
+    public void processRecords(List<Account> accounts) {
+        // Collections for different DML operations
+        List<Contact> contactsToInsert = new List<Contact>();
+        List<Contact> contactsToUpdate = new List<Contact>();
+        List<Contact> contactsToDelete = new List<Contact>();
+
+        // Query existing contacts once
+        Set<Id> accountIds = new Set<Id>();
+        for (Account acc : accounts) {
+            accountIds.add(acc.Id);
+        }
+
+        Map<Id, Contact> existingContacts = new Map<Id, Contact>();
+        for (Contact c : [
+            SELECT Id, AccountId, Email, IsInactive__c
+            FROM Contact
+            WHERE AccountId IN :accountIds
+        ]) {
+            existingContacts.put(c.AccountId, c);
+        }
+
+        // Process and categorize
+        for (Account acc : accounts) {
+            Contact existing = existingContacts.get(acc.Id);
+
+            if (existing == null) {
+                // No contact exists - INSERT
+                contactsToInsert.add(new Contact(
+                    FirstName = 'Auto',
+                    LastName = 'Generated',
+                    AccountId = acc.Id
+                ));
+            } else if (existing.IsInactive__c) {
+                // Inactive contact - DELETE
+                contactsToDelete.add(existing);
+            } else {
+                // Active contact - UPDATE
+                existing.LastActivityDate__c = Date.today();
+                contactsToUpdate.add(existing);
+            }
+        }
+
+        // Execute DML operations (3 statements max, regardless of record count)
+        if (!contactsToInsert.isEmpty()) {
+            insert contactsToInsert;
+        }
+        if (!contactsToUpdate.isEmpty()) {
+            update contactsToUpdate;
+        }
+        if (!contactsToDelete.isEmpty()) {
+            delete contactsToDelete;
+        }
+    }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// PATTERN: UPSERT FOR INSERT-OR-UPDATE LOGIC
+// ═══════════════════════════════════════════════════════════════════════════
+
+public class UpsertPatternService {
+
+    /**
+     * When you need to insert if not exists, update if exists
+     * Use UPSERT with an External ID field
+     */
+    public void syncExternalContacts(List<ExternalContact> externalData) {
+        List<Contact> contactsToUpsert = new List<Contact>();
+
+        for (ExternalContact ext : externalData) {
+            Contact c = new Contact(
+                External_Id__c = ext.id,  // External ID field
+                FirstName = ext.firstName,
+                LastName = ext.lastName,
+                Email = ext.email
+            );
+            contactsToUpsert.add(c);
+        }
+
+        // Single upsert handles both insert and update
+        if (!contactsToUpsert.isEmpty()) {
+            upsert contactsToUpsert External_Id__c;
+        }
+    }
+
+    // Wrapper class for external data
+    public class ExternalContact {
+        public String id;
+        public String firstName;
+        public String lastName;
+        public String email;
+    }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// PATTERN: PARTIAL SUCCESS HANDLING
+// ═══════════════════════════════════════════════════════════════════════════
+
+public class PartialSuccessService {
+
+    /**
+     * Handle partial failures gracefully
+     * Use Database.insert with allOrNone = false
+     */
+    public List<Database.SaveResult> insertWithPartialSuccess(List<Contact> contacts) {
+        if (contacts.isEmpty()) {
+            return new List<Database.SaveResult>();
+        }
+
+        // allOrNone = false allows partial success
+        List<Database.SaveResult> results = Database.insert(contacts, false);
+
+        // Log failures for analysis
+        for (Integer i = 0; i < results.size(); i++) {
+            Database.SaveResult sr = results[i];
+            if (!sr.isSuccess()) {
+                for (Database.Error err : sr.getErrors()) {
+                    System.debug(LoggingLevel.ERROR,
+                        'Failed to insert contact: ' + contacts[i] +
+                        ' Error: ' + err.getMessage()
+                    );
+                }
+            }
+        }
+
+        return results;
+    }
+}

package/skills/debugging-apex-logs/assets/null-pointer-fix.cls

@@ -0,0 +1,252 @@
+/**
+ * NULL POINTER EXCEPTION FIX PATTERNS
+ *
+ * Problem: System.NullPointerException when accessing null object properties
+ * Detection: DEBUG LOG shows EXCEPTION_THROWN|NullPointerException
+ *
+ * This template demonstrates null-safe coding patterns.
+ */
+
+// ═══════════════════════════════════════════════════════════════════════════
+// PATTERN 1: SOQL QUERY RETURNING NO RESULTS
+// ═══════════════════════════════════════════════════════════════════════════
+
+public class QueryNullSafety {
+
+    // BEFORE: Dangerous - throws exception if no results
+    public String getAccountNameUNSAFE(Id accountId) {
+        Account acc = [SELECT Name FROM Account WHERE Id = :accountId];
+        return acc.Name;  // NullPointerException if query returns nothing!
+    }
+
+    // AFTER: Safe - using List and isEmpty check
+    public String getAccountNameSAFE(Id accountId) {
+        List<Account> accounts = [SELECT Name FROM Account WHERE Id = :accountId LIMIT 1];
+
+        if (accounts.isEmpty()) {
+            return null;  // Or throw custom exception, or return default
+        }
+
+        return accounts[0].Name;
+    }
+
+    // AFTER: Safe - using Safe Navigation Operator (API 62.0+)
+    public String getAccountNameSafeNav(Id accountId) {
+        Account acc = [SELECT Name FROM Account WHERE Id = :accountId LIMIT 1];
+        return acc?.Name;  // Returns null instead of throwing exception
+    }
+
+    // AFTER: With default value
+    public String getAccountNameWithDefault(Id accountId, String defaultName) {
+        List<Account> accounts = [SELECT Name FROM Account WHERE Id = :accountId LIMIT 1];
+        return accounts.isEmpty() ? defaultName : accounts[0].Name;
+    }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// PATTERN 2: MAP ACCESS
+// ═══════════════════════════════════════════════════════════════════════════
+
+public class MapNullSafety {
+
+    // BEFORE: Dangerous - Map.get() returns null for missing keys
+    public void processAccountUNSAFE(Map<Id, Account> accountMap, Id targetId) {
+        Account acc = accountMap.get(targetId);
+        String name = acc.Name;  // NullPointerException if targetId not in map!
+    }
+
+    // AFTER: Check containsKey first
+    public void processAccountSAFE(Map<Id, Account> accountMap, Id targetId) {
+        if (accountMap.containsKey(targetId)) {
+            Account acc = accountMap.get(targetId);
+            String name = acc.Name;
+            // Process...
+        }
+    }
+
+    // AFTER: Check for null after get
+    public void processAccountNullCheck(Map<Id, Account> accountMap, Id targetId) {
+        Account acc = accountMap.get(targetId);
+        if (acc != null) {
+            String name = acc.Name;
+            // Process...
+        }
+    }
+
+    // AFTER: Safe navigation (API 62.0+)
+    public String getAccountNameFromMap(Map<Id, Account> accountMap, Id targetId) {
+        return accountMap.get(targetId)?.Name;
+    }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// PATTERN 3: RELATIONSHIP FIELDS
+// ═══════════════════════════════════════════════════════════════════════════
+
+public class RelationshipNullSafety {
+
+    // BEFORE: Dangerous - parent record might be null
+    public String getOwnerEmailUNSAFE(Contact c) {
+        return c.Account.Owner.Email;  // Multiple potential null points!
+    }
+
+    // AFTER: Check each level
+    public String getOwnerEmailSAFE(Contact c) {
+        if (c == null) return null;
+        if (c.Account == null) return null;
+        if (c.Account.Owner == null) return null;
+        return c.Account.Owner.Email;
+    }
+
+    // AFTER: Safe navigation chain (API 62.0+)
+    public String getOwnerEmailSafeNav(Contact c) {
+        return c?.Account?.Owner?.Email;
+    }
+
+    // AFTER: With default value
+    public String getOwnerEmailWithDefault(Contact c, String defaultEmail) {
+        String email = c?.Account?.Owner?.Email;
+        return String.isBlank(email) ? defaultEmail : email;
+    }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// PATTERN 4: LIST ACCESS
+// ═══════════════════════════════════════════════════════════════════════════
+
+public class ListNullSafety {
+
+    // BEFORE: Dangerous - list might be null or empty
+    public Contact getFirstContactUNSAFE(List<Contact> contacts) {
+        return contacts[0];  // IndexOutOfBoundsException if empty!
+    }
+
+    // AFTER: Check null and empty
+    public Contact getFirstContactSAFE(List<Contact> contacts) {
+        if (contacts == null || contacts.isEmpty()) {
+            return null;
+        }
+        return contacts[0];
+    }
+
+    // Pattern: Null-safe iteration
+    public void processContactsSAFE(List<Contact> contacts) {
+        // This is safe - for loop on null list doesn't execute
+        for (Contact c : contacts ?? new List<Contact>()) {
+            // Process contact
+        }
+    }
+
+    // Alternative: Early return
+    public void processContactsEarlyReturn(List<Contact> contacts) {
+        if (contacts == null || contacts.isEmpty()) {
+            return;
+        }
+
+        for (Contact c : contacts) {
+            // Process contact
+        }
+    }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// PATTERN 5: STRING OPERATIONS
+// ═══════════════════════════════════════════════════════════════════════════
+
+public class StringNullSafety {
+
+    // BEFORE: Dangerous - string might be null
+    public Boolean containsKeywordUNSAFE(String text, String keyword) {
+        return text.contains(keyword);  // NullPointerException if text is null!
+    }
+
+    // AFTER: Use String.isNotBlank() or String.isBlank()
+    public Boolean containsKeywordSAFE(String text, String keyword) {
+        if (String.isBlank(text) || String.isBlank(keyword)) {
+            return false;
+        }
+        return text.contains(keyword);
+    }
+
+    // Pattern: Null-safe string comparison
+    public Boolean isEqualSAFE(String a, String b) {
+        // Both null = equal
+        if (a == null && b == null) return true;
+        // One null = not equal
+        if (a == null || b == null) return false;
+        // Both non-null = compare
+        return a.equals(b);
+    }
+
+    // Pattern: Default value for null strings
+    public String getNameWithDefault(Account acc) {
+        return String.isBlank(acc?.Name) ? 'Unnamed Account' : acc.Name;
+    }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// PATTERN 6: TRIGGER CONTEXT
+// ═══════════════════════════════════════════════════════════════════════════
+
+public class TriggerNullSafety {
+
+    /**
+     * In triggers, old values might not exist (insert)
+     * and new values might not exist (delete)
+     */
+    public void handleTrigger() {
+        // Safe: Check context first
+        if (Trigger.isInsert) {
+            // Trigger.old is null in insert context
+            for (Account acc : (List<Account>)Trigger.new) {
+                // Process new records
+            }
+        }
+
+        if (Trigger.isUpdate) {
+            Map<Id, Account> oldMap = (Map<Id, Account>)Trigger.oldMap;
+            for (Account newAcc : (List<Account>)Trigger.new) {
+                Account oldAcc = oldMap.get(newAcc.Id);
+                // Both old and new are available
+                if (oldAcc.Status__c != newAcc.Status__c) {
+                    // Status changed
+                }
+            }
+        }
+
+        if (Trigger.isDelete) {
+            // Trigger.new is null in delete context
+            for (Account acc : (List<Account>)Trigger.old) {
+                // Process deleted records
+            }
+        }
+    }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// ANTI-PATTERN: OVER-DEFENSIVE CODING
+// ═══════════════════════════════════════════════════════════════════════════
+
+public class OverDefensiveCoding {
+
+    /**
+     * Don't check for null when it's impossible
+     * This adds unnecessary code and cognitive load
+     */
+
+    // UNNECESSARY: Trigger.new is never null in insert/update context
+    public void badExample() {
+        if (Trigger.new != null && !Trigger.new.isEmpty()) {
+            for (SObject record : Trigger.new) {
+                // Trigger.new is guaranteed non-null in before/after insert/update
+            }
+        }
+    }
+
+    // CORRECT: Trust the platform guarantees
+    public void goodExample() {
+        for (Account acc : (List<Account>)Trigger.new) {
+            // Just use it - Trigger.new is guaranteed in this context
+        }
+    }
+}

package/skills/debugging-apex-logs/assets/soql-in-loop-fix.cls

@@ -0,0 +1,157 @@
+/**
+ * SOQL IN LOOP FIX PATTERN
+ *
+ * Problem: SOQL queries inside loops consume governor limits rapidly
+ * Detection: DEBUG LOG shows repeated SOQL_EXECUTE_BEGIN entries
+ * Limit: 100 SOQL queries per synchronous transaction
+ *
+ * This template demonstrates the bulkification pattern to fix SOQL in loops.
+ */
+
+// ═══════════════════════════════════════════════════════════════════════════
+// BEFORE: SOQL IN LOOP (PROBLEMATIC)
+// ═══════════════════════════════════════════════════════════════════════════
+
+public class AccountService_BEFORE {
+
+    // This method will fail if accounts.size() > 100
+    public void processAccounts(List<Account> accounts) {
+        for (Account acc : accounts) {
+            // SOQL inside loop - each iteration uses 1 query
+            Contact primaryContact = [
+                SELECT Id, Email, Phone
+                FROM Contact
+                WHERE AccountId = :acc.Id
+                AND IsPrimary__c = true
+                LIMIT 1
+            ];
+
+            if (primaryContact != null) {
+                acc.Primary_Contact_Email__c = primaryContact.Email;
+            }
+        }
+    }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// AFTER: BULKIFIED PATTERN (CORRECT)
+// ═══════════════════════════════════════════════════════════════════════════
+
+public class AccountService_AFTER {
+
+    // This method uses only 1 SOQL query regardless of accounts.size()
+    public void processAccounts(List<Account> accounts) {
+        // Step 1: Collect all Account IDs
+        Set<Id> accountIds = new Set<Id>();
+        for (Account acc : accounts) {
+            accountIds.add(acc.Id);
+        }
+
+        // Step 2: Single SOQL query BEFORE the loop
+        Map<Id, Contact> primaryContactsByAccountId = new Map<Id, Contact>();
+        for (Contact c : [
+            SELECT Id, Email, Phone, AccountId
+            FROM Contact
+            WHERE AccountId IN :accountIds
+            AND IsPrimary__c = true
+        ]) {
+            primaryContactsByAccountId.put(c.AccountId, c);
+        }
+
+        // Step 3: Access from Map inside loop (no SOQL)
+        for (Account acc : accounts) {
+            Contact primaryContact = primaryContactsByAccountId.get(acc.Id);
+            if (primaryContact != null) {
+                acc.Primary_Contact_Email__c = primaryContact.Email;
+            }
+        }
+    }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// ADVANCED: NESTED RELATIONSHIP PATTERN
+// ═══════════════════════════════════════════════════════════════════════════
+
+public class OrderService_Bulkified {
+
+    // Complex scenario: Orders → Accounts → Contacts
+    public void processOrders(List<Order> orders) {
+        // Collect all Account IDs from Orders
+        Set<Id> accountIds = new Set<Id>();
+        for (Order o : orders) {
+            if (o.AccountId != null) {
+                accountIds.add(o.AccountId);
+            }
+        }
+
+        // Query Accounts with related Contacts in ONE query (relationship query)
+        Map<Id, Account> accountsWithContacts = new Map<Id, Account>([
+            SELECT Id, Name,
+                   (SELECT Id, Email FROM Contacts WHERE IsPrimary__c = true LIMIT 1)
+            FROM Account
+            WHERE Id IN :accountIds
+        ]);
+
+        // Process orders using the pre-queried data
+        for (Order o : orders) {
+            Account acc = accountsWithContacts.get(o.AccountId);
+            if (acc != null && !acc.Contacts.isEmpty()) {
+                o.Notification_Email__c = acc.Contacts[0].Email;
+            }
+        }
+    }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// PATTERN: MAP FACTORY FOR REUSABLE QUERIES
+// ═══════════════════════════════════════════════════════════════════════════
+
+public class ContactQueryService {
+
+    /**
+     * Factory method to get primary contacts by Account ID
+     * Reusable across multiple services
+     */
+    public static Map<Id, Contact> getPrimaryContactsByAccountId(Set<Id> accountIds) {
+        Map<Id, Contact> result = new Map<Id, Contact>();
+
+        if (accountIds.isEmpty()) {
+            return result;
+        }
+
+        for (Contact c : [
+            SELECT Id, FirstName, LastName, Email, Phone, AccountId
+            FROM Contact
+            WHERE AccountId IN :accountIds
+            AND IsPrimary__c = true
+        ]) {
+            result.put(c.AccountId, c);
+        }
+
+        return result;
+    }
+
+    /**
+     * Get all contacts grouped by Account ID
+     * Returns Map<AccountId, List<Contact>>
+     */
+    public static Map<Id, List<Contact>> getContactsGroupedByAccount(Set<Id> accountIds) {
+        Map<Id, List<Contact>> result = new Map<Id, List<Contact>>();
+
+        // Initialize empty lists for all accounts
+        for (Id accId : accountIds) {
+            result.put(accId, new List<Contact>());
+        }
+
+        for (Contact c : [
+            SELECT Id, FirstName, LastName, Email, Phone, AccountId
+            FROM Contact
+            WHERE AccountId IN :accountIds
+            ORDER BY CreatedDate DESC
+        ]) {
+            result.get(c.AccountId).add(c);
+        }
+
+        return result;
+    }
+}

package/skills/debugging-apex-logs/references/analysis-playbook.md

@@ -0,0 +1,53 @@
+# Debug Analysis Playbook
+
+Use this playbook when `debugging-apex-logs` is active and you need the expanded workflow.
+
+## 1. Gather context
+
+Collect:
+- org alias
+- failing transaction or test context
+- approximate time window
+- relevant user / record / request identifiers
+
+## 2. Retrieve logs
+
+Preferred commands:
+
+```bash
+sf apex list log --target-org <alias> --json
+sf apex get log --log-id <id> --target-org <alias>
+sf apex tail log --target-org <alias> --color
+```
+
+See [cli-commands.md](cli-commands.md) for more options.
+
+## 3. Analyze in this order
+
+1. transaction entry point
+2. exceptions and fatal errors
+3. governor limits
+4. SOQL / DML repetition patterns
+5. CPU / heap hotspots
+6. callout timing and external failures
+
+## 4. Classify severity
+
+- **Critical** — runtime failure, hard limit, data corruption risk
+- **Warning** — near-limit, non-selective query, slow path
+- **Info** — optimization opportunity, cleanup item, observability gap
+
+## 5. Propose fixes
+
+Prefer fixes that are:
+- root-cause oriented
+- bulk-safe
+- testable
+- deployable in one clean change set
+
+## 6. Loop with adjacent skills
+
+- use `sf-apex` for code fixes
+- use `running-apex-tests` to reproduce and verify
+- use `deploying-metadata` to deploy fixes
+- use `handling-sf-data` when the issue depends on missing or malformed test data