acek-skills 1.0.0

package/skills/sf-data-migration/SKILL.md

@@ -0,0 +1,374 @@
+---
+name: sf-data-migration
+description: >
+  Use this skill for Salesforce data migration, bulk data operations, and data management tasks:
+  designing import/export strategies, writing Data Loader automation scripts, upsert operations
+  with External IDs, bulk SOQL exports, data cleansing before migration, error handling for bulk
+  loads, and generating data migration plans. Trigger when the user mentions "data migration",
+  "bulk import", "data loader", "upsert", "external ID", "migrate records", "export data",
+  "data cleansing", "bulk delete", "mass update", or asks how to move large volumes of records
+  between orgs or from external systems into Salesforce.
+---
+
+# Salesforce Data Migration Skill
+
+## Environment Context
+- API Version: **61.0**
+- Tooling: **SF CLI** (`sf data` commands) for dev/test volumes; Data Loader for production volumes
+- Always migrate to **sandbox first**, verify, then production
+- Single org: sandbox → production
+
+---
+
+## Migration Planning — Before Touching Any Data
+
+### Step 1: Discovery Checklist
+- [ ] What objects and how many records? (run COUNT queries first)
+- [ ] Are there required fields that source data may not have?
+- [ ] Are there lookup/relationship fields? (parent records must exist first)
+- [ ] Are there Record Types? (map source values to Salesforce Record Type IDs)
+- [ ] Are there Validation Rules that will block import? (consider deactivating temporarily)
+- [ ] Are there Triggers/Flows that fire on insert/update? (decide: bypass or let fire?)
+- [ ] Does the source data have a unique identifier for upsert (External ID)?
+- [ ] What is the target volume? (under 10K → SF CLI; over 10K → Data Loader / Bulk API)
+
+### Step 2: Dependency Order
+Always load in parent → child order:
+```
+1. Custom Metadata / Reference Data (e.g. picklist-driving records)
+2. Accounts
+3. Contacts (requires Account)
+4. Opportunities (requires Account)
+5. Opportunity Products (requires Opportunity + Pricebook Entry)
+6. Cases (requires Account + Contact)
+7. Custom Objects (based on lookup dependency)
+```
+
+### Step 3: External ID Strategy
+Every migrated object should have an External ID field to enable upsert and relationship mapping.
+
+```apex
+// External ID field naming convention:
+ExternalId__c         // generic
+LegacySystemId__c     // named after source system
+SapId__c, OracleId__c // system-specific
+```
+
+Field settings:
+- Type: Text (or Number if IDs are numeric)
+- Mark as: **External ID** ✓ and **Unique** ✓
+- Max length: match source system ID length
+
+---
+
+## SF CLI Data Commands — Dev/Test Volumes (<50K records)
+
+### Query & Export
+```bash
+# Basic query to CSV
+sf data query \
+  --query "SELECT Id, Name, Industry, Phone FROM Account WHERE CreatedDate = THIS_YEAR" \
+  --target-org <alias> \
+  --result-format csv > exports/accounts.csv
+
+# Export with relationships
+sf data query \
+  --query "SELECT Id, Name, Account.Name, Email FROM Contact WHERE AccountId != null" \
+  --target-org <alias> \
+  --result-format csv > exports/contacts.csv
+
+# Count records before migration
+sf data query \
+  --query "SELECT COUNT() FROM Account" \
+  --target-org <alias>
+
+# Export with Bulk API (for larger volumes)
+sf data export bulk \
+  --query "SELECT Id, Name, ExternalId__c FROM Account" \
+  --output-file exports/accounts-bulk.csv \
+  --target-org <alias>
+```
+
+### Import / Upsert
+```bash
+# Insert new records
+sf data import bulk \
+  --sobject Account \
+  --file imports/accounts.csv \
+  --target-org <alias>
+
+# Upsert (insert + update based on External ID)
+sf data upsert bulk \
+  --sobject Account \
+  --file imports/accounts.csv \
+  --external-id ExternalId__c \
+  --target-org <alias>
+
+# Delete records
+sf data delete bulk \
+  --sobject Account \
+  --file exports/accounts-to-delete.csv \
+  --target-org <alias>
+```
+
+### Check Job Status
+```bash
+sf data bulk results \
+  --job-id <JobId> \
+  --target-org <alias>
+```
+
+---
+
+## Data Loader — Production Volumes (>50K records)
+
+Data Loader uses Bulk API 2.0 by default. Use for production migration.
+
+### CSV Requirements
+- UTF-8 encoding (no BOM)
+- First row: field API names (e.g. `Name,ExternalId__c,Industry__c`)
+- `null` to clear a field: leave cell empty OR use `#N/A` for some fields
+- Date format: `YYYY-MM-DDThh:mm:ss.000Z` (ISO 8601)
+- Boolean: `true` / `false` (lowercase)
+- Currency: numeric only, no currency symbols
+
+### Batch Size Recommendations
+| Volume | Batch Size | Concurrency |
+|---|---|---|
+| < 10K | 200 | Serial |
+| 10K – 100K | 2,000 | Parallel |
+| 100K – 1M | 10,000 | Parallel |
+| > 1M | 10,000 | Parallel + schedule overnight |
+
+### Error Handling
+- Always save the **success file** and **error file** per run
+- Error file contains failed rows + error message — fix and re-run only errors
+- Common errors and fixes:
+
+| Error | Cause | Fix |
+|---|---|---|
+| `REQUIRED_FIELD_MISSING` | Required field empty in CSV | Fill required fields; check validation rules |
+| `INVALID_FIELD` | Field API name wrong | Check with `sf sobject describe --sobject <Object>` |
+| `FIELD_INTEGRITY_EXCEPTION` | Lookup ID doesn't exist in org | Load parent records first |
+| `DUPLICATE_VALUE` | Unique field already exists | Switch from insert to upsert with External ID |
+| `STRING_TOO_LONG` | Value exceeds field length | Truncate or increase field length |
+| `CANNOT_INSERT_UPDATE_ACTIVATE_ENTITY` | Trigger/validation blocking | Check trigger logic; may need to deactivate VR temporarily |
+
+---
+
+## Upsert Pattern — External ID Relationship Mapping
+
+When loading child records and parent exists via External ID (not Salesforce ID):
+
+### CSV Format
+Instead of using Salesforce `AccountId`, reference the parent's External ID:
+
+```csv
+Name,Email,Account.ExternalId__c
+John Doe,john@example.com,ACC-12345
+Jane Smith,jane@example.com,ACC-67890
+```
+
+Salesforce resolves `Account.ExternalId__c` to the Account's Salesforce ID automatically during upsert.
+
+### Upsert Command
+```bash
+sf data upsert bulk \
+  --sobject Contact \
+  --file imports/contacts-with-account-ref.csv \
+  --external-id ExternalId__c \
+  --target-org <alias>
+```
+
+---
+
+## Data Cleansing — Before Migration
+
+### Common Issues to Fix in Source Data
+
+```python
+# Python script example — clean CSV before Salesforce import
+
+import pandas as pd
+
+df = pd.read_csv('raw_export.csv')
+
+# Remove duplicates on External ID
+df = df.drop_duplicates(subset=['external_id'])
+
+# Truncate strings to Salesforce field limits
+df['name'] = df['name'].str[:255]           # Text field max
+df['description'] = df['description'].str[:32000]  # Long Text max
+
+# Normalize phone numbers
+df['phone'] = df['phone'].str.replace(r'\D', '', regex=True)
+
+# Map picklist values to Salesforce API values
+industry_map = {
+    'Tech': 'Technology',
+    'Fin': 'Finance',
+    'Health': 'Healthcare'
+}
+df['industry'] = df['industry'].map(industry_map)
+
+# Convert date format to ISO 8601
+df['created_date'] = pd.to_datetime(df['created_date']).dt.strftime('%Y-%m-%dT%H:%M:%S.000Z')
+
+# Replace NaN with empty string
+df = df.fillna('')
+
+df.to_csv('cleaned_export.csv', index=False, encoding='utf-8')
+print(f"Cleaned: {len(df)} records")
+```
+
+### SOQL-Based Deduplication Check
+```bash
+# Find duplicates in Salesforce by External ID
+sf data query \
+  --query "SELECT ExternalId__c, COUNT(Id) total FROM Account GROUP BY ExternalId__c HAVING COUNT(Id) > 1" \
+  --target-org <alias>
+
+# Find records without External ID (not upsert-safe)
+sf data query \
+  --query "SELECT Id, Name FROM Account WHERE ExternalId__c = null LIMIT 200" \
+  --target-org <alias>
+```
+
+---
+
+## Apex Batch for Large-Scale Updates
+
+When you need to transform/update data already in Salesforce at scale:
+
+```apex
+public class AccountMigrationBatch implements Database.Batchable<SObject>, Database.Stateful {
+    private Integer successCount = 0;
+    private Integer errorCount = 0;
+    private List<String> errors = new List<String>();
+
+    public Database.QueryLocator start(Database.BatchableContext bc) {
+        return Database.getQueryLocator(
+            'SELECT Id, Name, LegacyStatus__c, Status__c ' +
+            'FROM Account WHERE MigrationComplete__c = false'
+        );
+    }
+
+    public void execute(Database.BatchableContext bc, List<Account> scope) {
+        List<Account> toUpdate = new List<Account>();
+
+        for (Account acc : scope) {
+            // Transform logic
+            acc.Status__c = mapStatus(acc.LegacyStatus__c);
+            acc.MigrationComplete__c = true;
+            toUpdate.add(acc);
+        }
+
+        Database.SaveResult[] results = Database.update(toUpdate, false); // allOrNone=false
+        for (Integer i = 0; i < results.size(); i++) {
+            if (results[i].isSuccess()) {
+                successCount++;
+            } else {
+                errorCount++;
+                errors.add(toUpdate[i].Id + ': ' + results[i].getErrors()[0].getMessage());
+            }
+        }
+    }
+
+    public void finish(Database.BatchableContext bc) {
+        // Send summary email or create log record
+        System.debug('Migration complete. Success: ' + successCount + ', Errors: ' + errorCount);
+        for (String err : errors) {
+            System.debug('ERROR: ' + err);
+        }
+    }
+
+    private String mapStatus(String legacyStatus) {
+        Map<String, String> statusMap = new Map<String, String>{
+            'A' => 'Active',
+            'I' => 'Inactive',
+            'P' => 'Pending'
+        };
+        return statusMap.containsKey(legacyStatus) ? statusMap.get(legacyStatus) : 'Unknown';
+    }
+}
+```
+
+### Execute Batch
+```apex
+// In Anonymous Apex
+Database.executeBatch(new AccountMigrationBatch(), 200); // 200 records per batch
+```
+
+---
+
+## Migration Runbook Template
+
+File: `instructions/migration/YYYYMMDD-<migration-name>-runbook.md`
+
+```markdown
+# Migration Runbook: [Migration Name]
+
+**Date:** YYYY-MM-DD
+**Target Org:** [{{DEV_ORG_ALIAS}} / {{PROD_ORG_ALIAS}}]
+**Estimated Volume:** [X records across Y objects]
+**Estimated Duration:** [X hours]
+
+---
+
+## Pre-Migration Checklist
+- [ ] Backup current data (export all affected objects)
+- [ ] Verify External ID field exists on all target objects
+- [ ] Test migration in sandbox with 10% sample — confirm success rate > 99%
+- [ ] Identify Validation Rules to deactivate temporarily (list below)
+- [ ] Identify Triggers/Flows that will fire — confirm acceptable behavior
+- [ ] Communicate downtime window to affected users (if any)
+- [ ] Confirm Data Loader / SF CLI version is current
+
+## Validation Rules to Deactivate During Migration
+| Object | Validation Rule | Reason to Deactivate |
+|---|---|---|
+| Account | ACCOUNT_RequireIndustry | Source data may not have Industry |
+
+## Load Order
+1. [Object 1] — [file name] — [estimated records]
+2. [Object 2] — [file name] — [estimated records]
+
+## Rollback Plan
+If error rate > 5% or critical data issue found:
+1. Stop migration immediately
+2. Export all records inserted this session (filter by CreatedDate = TODAY)
+3. Delete inserted records using error-free export CSV + sf data delete bulk
+4. Restore Validation Rules
+5. Investigate root cause before re-attempting
+
+## Post-Migration Verification
+- [ ] Record counts match source system
+- [ ] Sample 10 records manually — verify all fields correct
+- [ ] Lookup relationships intact (spot-check Contacts → Accounts)
+- [ ] Validation Rules re-activated
+- [ ] Users notified migration complete
+
+## Results
+| Object | Inserted | Updated | Failed | Notes |
+|---|---|---|---|---|
+| Account | | | | |
+| Contact | | | | |
+```
+
+---
+
+## SF CLI Quick Reference — Data Commands
+
+```bash
+# Describe object fields (use to verify API names before import)
+sf sobject describe --sobject Account --target-org <alias>
+
+# Query to verify post-migration counts
+sf data query --query "SELECT COUNT() FROM Account WHERE ExternalId__c != null" --target-org <alias>
+
+# Get Bulk API job results
+sf data bulk results --job-id <JobId> --target-org <alias>
+
+# List all Bulk API jobs (recent)
+sf data bulk status --target-org <alias>
+```

package/skills/sf-dev/SKILL.md

@@ -0,0 +1,328 @@
+---
+name: sf-dev
+description: >
+  Use this skill for ANY Salesforce custom development task: writing or reviewing Apex classes,
+  triggers, batch jobs, test classes, SOQL queries, LWC components (HTML/JS/CSS), Aura components,
+  and integration patterns. Trigger this skill whenever the user mentions Apex, LWC, SOQL, triggers,
+  @AuraEnabled, @wire, REST/SOAP callouts, platform events, or asks to build/fix/refactor any
+  Salesforce code. Also use when the user asks about governor limits, test coverage, or debugging
+  Salesforce-specific runtime errors.
+---
+
+# Salesforce Developer Skill
+
+## Environment Context
+- API Version: **61.0**
+- Tooling: **SF CLI** (`sf` commands)
+- Apex LSP: **offline** — never use compile-time SObject type references that require org metadata
+- Version control: **GitHub** (branching: `main → staging → develop → feature/*`)
+
+---
+
+## Apex — Core Rules
+
+### Governor Limits (non-negotiable)
+- **No SOQL inside loops** — always bulkify; query outside the loop, store in Map/List
+- **No DML inside loops** — collect records, DML once after loop
+- **No callouts inside loops**
+- Minimum test coverage: **85%** (aim for 90%+)
+
+### Security Patterns
+```apex
+// ✅ CRUD check — use Schema.getGlobalDescribe() (LSP-safe)
+if (!Schema.getGlobalDescribe().get('ObjectName').getDescribe().isCreateable()) {
+    throw new AuraHandledException('Insufficient permissions.');
+}
+
+// ❌ NEVER use compile-time reference (LSP offline can't resolve)
+// if (!ContentVersion.SObjectType.getDescribe().isCreateable()) { ... }
+```
+
+- `ContentDocumentLink`: skip explicit CRUD check — junction object protected by `with sharing` + try-catch
+- FLS check via `evDescribe.fields` not available offline — use object-level `isUpdateable()` only
+- All classes handling user data: use **`with sharing`**
+
+### @AuraEnabled Methods
+```apex
+@AuraEnabled
+public static Result myMethod(String param) {
+    try {
+        // business logic
+    } catch (Exception e) {
+        throw new AuraHandledException(e.getMessage());
+    }
+}
+```
+- Always wrap DML in try-catch → re-throw as `AuraHandledException`
+- Private helper methods: throw `CalloutException` (caller wraps it)
+
+### Exception Behavior (Salesforce by design)
+- `AuraHandledException.getMessage()` in test context **always** returns `'Script-thrown exception'`
+- In test assertions: `System.assertEquals('Script-thrown exception', e.getMessage())` — **do not change this**
+
+### Naming Conventions
+| Type | Convention | Example |
+|---|---|---|
+| Apex Class | PascalCase | `AccountHelper`, `OpportunityTrigger` |
+| Test Class | PascalCase + `Test` suffix | `AccountHelperTest` |
+| Custom Field | PascalCase__c | `ProjectStatus__c` |
+| Variable | camelCase | `accountList`, `oppMap` |
+
+### ApexDoc (required on all public methods)
+```apex
+/**
+ * @description Brief description of what this method does
+ * @param recordId The ID of the record to process
+ * @return List of processed results
+ * @throws AuraHandledException if user lacks required permissions
+ */
+@AuraEnabled
+public static List<Result__c> processRecord(Id recordId) { ... }
+```
+
+### Test Class Pattern
+```apex
+@isTest
+private class AccountHelperTest {
+    @TestSetup
+    static void makeData() {
+        // create test records once for all test methods
+    }
+
+    @isTest
+    static void testPositivePath() {
+        Test.startTest();
+        // call method
+        Test.stopTest();
+        // assert
+    }
+
+    @isTest
+    static void testNegativePath_insufficientPermission() {
+        // test exception path
+        try {
+            AccountHelper.myMethod(null);
+            System.assert(false, 'Expected exception not thrown');
+        } catch (AuraHandledException e) {
+            System.assertEquals('Script-thrown exception', e.getMessage());
+        }
+    }
+}
+```
+
+---
+
+## SOQL — Best Practices
+
+```apex
+// ✅ Bulkified pattern
+Map<Id, Account> accountMap = new Map<Id, Account>(
+    [SELECT Id, Name, OwnerId FROM Account WHERE Id IN :accountIds]
+);
+
+// ✅ Aggregate query
+List<AggregateResult> results = [
+    SELECT StageName, COUNT(Id) total
+    FROM Opportunity
+    WHERE CloseDate = THIS_YEAR
+    GROUP BY StageName
+];
+
+// ❌ Never SOQL in loop
+for (Account acc : accounts) {
+    List<Contact> contacts = [SELECT Id FROM Contact WHERE AccountId = :acc.Id]; // WRONG
+}
+```
+
+- Selective WHERE clauses: always filter on indexed fields (Id, Name, ExternalId__c, lookup fields)
+- Avoid `SELECT *` — always specify fields explicitly
+- Use `LIMIT` on unbounded queries
+
+---
+
+## LWC — Core Rules
+
+### File Structure
+```
+force-app/main/default/lwc/
+└── myComponent/
+    ├── myComponent.html
+    ├── myComponent.js
+    ├── myComponent.css
+    └── myComponent.js-meta.xml
+```
+
+### Naming
+- Component folder: **camelCase** (`accountCard`, `opportunityList`)
+- Never PascalCase for LWC folders
+
+### Brand Theme — MANDATORY `:host` block
+Every LWC CSS file must include this exact token block:
+
+```css
+:host {
+    /* ── Brand ── */
+    --brand:        #f37e20;
+    --brand-hover:  #d86a13;
+    --brand-light:  #ff9f4d;
+    --brand-dim:    rgba(243, 126, 32, 0.08);
+    --brand-border: rgba(243, 126, 32, 0.22);
+    --brand-shadow: rgba(243, 126, 32, 0.2);
+
+    /* ── User Accent ── */
+    --user-color:   #0070d2;
+
+    /* ── Text ── */
+    --text-primary:   #1d1c1d;
+    --text-secondary: #616061;
+    --text-muted:     #9b9a9b;
+
+    /* ── Surface ── */
+    --surface:      #ffffff;
+    --surface-dim:  #f8f8f8;
+    --border:       #e8e8e8;
+    --border-light: #f0f0f0;
+
+    /* ── Typography ── */
+    --font: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+    --mono: "SFMono-Regular", Consolas, "Liberation Mono", Menlo, Courier, monospace;
+
+    /* ── Radius ── */
+    --r-sm:  4px;
+    --r-md:  8px;
+    --r-lg:  12px;
+    --r-xl:  18px;
+    --r-pill: 999px;
+
+    /* ── Transition ── */
+    --t: 0.15s ease;
+}
+```
+
+**Token rules:**
+- ❌ Never hardcode `#f37e20` — always `var(--brand)`
+- ❌ Never use `var(--lwc-colorTextDefault)` for brand colors
+- ✅ Border-radius: always `var(--r-sm/md/lg/xl/r-pill)`
+- ✅ Font: `var(--font)` for UI text, `var(--mono)` for code/IDs
+- ✅ Transitions: `var(--t)` for hover/active
+
+### Version Badge — MANDATORY on every LWC
+Every LWC must display a version badge in its header/initiate screen.
+
+**Format:** `vMAJOR.MINOR.PATCH+SEASON'YEAR` → e.g. `v2.1.0+S'26`
+- SEASON codes: `S` = Summer, `Sp` = Spring, `W` = Winter
+- YEAR: last 2 digits of Salesforce release year
+
+```html
+<!-- HTML pattern -->
+<span class="myComponent-version-badge">v1.0.0<span class="badge-season">+S'26</span></span>
+```
+
+```css
+/* CSS pattern */
+.myComponent-version-badge {
+    display: inline-block;
+    font-size: 9px;
+    font-weight: 700;
+    color: var(--brand);
+    background: var(--brand-dim);
+    border: 1px solid var(--brand-border);
+    border-radius: var(--r-pill);
+    padding: 1px 7px;
+    letter-spacing: 0.5px;
+    text-transform: uppercase;
+}
+.myComponent-version-badge .badge-season {
+    margin-left: 2px;
+    font-weight: 800;
+}
+```
+
+**Version increment rules:**
+- New feature in a season → bump MINOR, reset PATCH to 0
+- Bugfix same season → bump PATCH only
+- Next Salesforce season → update SEASON+YEAR, evaluate MINOR bump
+
+### JS Best Practices
+```javascript
+import { LightningElement, api, wire, track } from 'lwc';
+
+export default class MyComponent extends LightningElement {
+    // @api for public properties (parent → child)
+    @api recordId;
+
+    // @track only needed for nested object/array mutation detection
+    // primitives are reactive by default
+
+    // ❌ Never use @wire adapter inside a loop
+    // ✅ Wire at component level, filter in getter
+    @wire(getRelatedItems, { recordId: '$recordId' })
+    wiredItems;
+
+    get processedItems() {
+        return this.wiredItems.data?.filter(i => i.Active__c) ?? [];
+    }
+}
+```
+
+- JSDoc required on all public methods and `@api` properties
+- Use optional chaining (`?.`) and nullish coalescing (`??`) for safety
+- Fire events upward with `CustomEvent`, never call parent methods directly
+
+---
+
+## Integration Patterns
+
+### REST Callout
+```apex
+HttpRequest req = new HttpRequest();
+req.setEndpoint('callout:My_Named_Credential/api/endpoint');
+req.setMethod('GET');
+req.setTimeout(10000);
+
+HttpResponse res = new Http().send(req);
+if (res.getStatusCode() != 200) {
+    throw new CalloutException('HTTP ' + res.getStatusCode() + ': ' + res.getBody());
+}
+```
+- Always use Named Credentials — never hardcode URLs or tokens
+- Set timeout explicitly
+- Throw `CalloutException` in helper; let `@AuraEnabled` caller wrap as `AuraHandledException`
+
+---
+
+## SF CLI — Common Dev Commands
+
+```bash
+# Pull metadata from org
+sf project retrieve start --metadata ApexClass:MyClass --target-org <alias>
+
+# Push local source to scratch org
+sf project deploy start --target-org <alias>
+
+# Run specific test
+sf apex run test --class-names MyClassTest --target-org <alias> --result-format human
+
+# Run all tests
+sf apex run test --test-level RunAllTestsInOrg --target-org <alias>
+
+# Open org in browser
+sf org open --target-org <alias>
+
+# Execute anonymous Apex
+sf apex run --target-org <alias> --file scripts/apex/myScript.apex
+```
+
+---
+
+## Code Review Checklist (before every PR)
+- [ ] No SOQL/DML inside loops
+- [ ] Test coverage ≥ 85%
+- [ ] No `@wire` in loops (LWC)
+- [ ] All public methods have ApexDoc/JSDoc
+- [ ] No hardcoded IDs, credentials, or org-specific values
+- [ ] `with sharing` declared on all Apex classes
+- [ ] CRUD check present where applicable (using `Schema.getGlobalDescribe()`)
+- [ ] All `@AuraEnabled` methods wrapped in try-catch → `AuraHandledException`
+- [ ] LWC has `:host` brand token block
+- [ ] LWC has version badge