@salesforce/afv-skills 1.8.0 → 1.9.0

package/skills/debugging-apex-logs/references/debug-log-reference.md

@@ -0,0 +1,328 @@
+<!-- Parent: debugging-apex-logs/SKILL.md -->
+# Salesforce Debug Log Reference
+
+## Log Structure
+
+Debug logs follow a consistent format:
+```
+TIMESTAMP|EVENT_IDENTIFIER|[PARAMS]|DETAILS
+```
+
+Example:
+```
+14:32:54.123 (123456789)|SOQL_EXECUTE_BEGIN|[45]|SELECT Id FROM Account
+```
+
+---
+
+## Event Categories
+
+### Execution Events
+
+| Event | Description | Analysis Notes |
+|-------|-------------|----------------|
+| `EXECUTION_STARTED` | Transaction begins | Identifies transaction type |
+| `EXECUTION_FINISHED` | Transaction ends | Total execution time |
+| `CODE_UNIT_STARTED` | Method/trigger entry | Call stack tracing |
+| `CODE_UNIT_FINISHED` | Method/trigger exit | Method duration |
+
+### SOQL Events
+
+| Event | Description | Key Fields |
+|-------|-------------|------------|
+| `SOQL_EXECUTE_BEGIN` | Query starts | Line number, Query text |
+| `SOQL_EXECUTE_END` | Query ends | Rows returned |
+
+**Analysis Pattern:**
+```
+|SOQL_EXECUTE_BEGIN|[45]|SELECT Id, Name FROM Account WHERE...
+|SOQL_EXECUTE_END|[3 rows]
+```
+- Line 45 in source code
+- Query returned 3 rows
+
+**Warning Signs:**
+- Same query appearing multiple times → SOQL in loop
+- `[100000 rows]` → Non-selective query
+- Query without WHERE clause → Full table scan
+
+### DML Events
+
+| Event | Description | Key Fields |
+|-------|-------------|------------|
+| `DML_BEGIN` | DML starts | Line number, Operation type, Object |
+| `DML_END` | DML ends | Rows affected |
+
+**Analysis Pattern:**
+```
+|DML_BEGIN|[78]|Op:Insert|Type:Contact|
+|DML_END|[200 rows]
+```
+- Line 78: INSERT operation
+- 200 Contact records inserted
+
+**Warning Signs:**
+- Same DML operation appearing multiple times → DML in loop
+- DML after each SOQL → Likely unbulkified code
+
+### Limit Events
+
+| Event | Description | Format |
+|-------|-------------|--------|
+| `LIMIT_USAGE` | Current limit usage | `LIMIT_NAME|used|max` |
+| `LIMIT_USAGE_FOR_NS` | Per-namespace limits | `LIMIT_NAME|used|max|namespace` |
+| `CUMULATIVE_LIMIT_USAGE` | End of transaction | Summary of all limits |
+
+**Example:**
+```
+|LIMIT_USAGE|SOQL_QUERIES|25|100
+|LIMIT_USAGE|DML_STATEMENTS|45|150
+|LIMIT_USAGE|CPU_TIME|3500|10000
+|LIMIT_USAGE|HEAP_SIZE|2500000|6000000
+```
+
+### Exception Events
+
+| Event | Description | Format |
+|-------|-------------|--------|
+| `EXCEPTION_THROWN` | Exception occurs | `[line]|ExceptionType|Message` |
+| `FATAL_ERROR` | Unhandled exception | Full stack trace |
+
+**Analysis Pattern:**
+```
+|EXCEPTION_THROWN|[67]|System.NullPointerException|Attempt to de-reference a null object
+|FATAL_ERROR|System.NullPointerException: Attempt to de-reference a null object
+  Class.ContactService.processContacts: line 67, column 1
+  Class.AccountTriggerHandler.afterUpdate: line 34, column 1
+  Trigger.AccountTrigger: line 5, column 1
+```
+
+### Method Events
+
+| Event | Description | Use Case |
+|-------|-------------|----------|
+| `METHOD_ENTRY` | Method called | Call hierarchy |
+| `METHOD_EXIT` | Method returns | Method duration |
+| `CONSTRUCTOR_ENTRY` | Constructor called | Object creation |
+| `CONSTRUCTOR_EXIT` | Constructor returns | |
+
+### Loop Events
+
+| Event | Description | Important For |
+|-------|-------------|---------------|
+| `LOOP_BEGIN` | Loop starts | SOQL/DML in loop detection |
+| `LOOP_END` | Loop ends | |
+| `ITERATION_BEGIN` | Loop iteration | Iteration count |
+| `ITERATION_END` | Iteration ends | |
+
+**Detection Pattern for SOQL in Loop:**
+```
+|LOOP_BEGIN|
+  |ITERATION_BEGIN|
+    |SOQL_EXECUTE_BEGIN|[45]|SELECT...
+    |SOQL_EXECUTE_END|[1 rows]
+  |ITERATION_END|
+  |ITERATION_BEGIN|
+    |SOQL_EXECUTE_BEGIN|[45]|SELECT...  ← Same query repeating!
+    |SOQL_EXECUTE_END|[1 rows]
+  |ITERATION_END|
+|LOOP_END|
+```
+
+### Callout Events
+
+| Event | Description | Key Fields |
+|-------|-------------|------------|
+| `CALLOUT_EXTERNAL_ENTRY` | HTTP callout starts | Endpoint URL |
+| `CALLOUT_EXTERNAL_EXIT` | HTTP callout ends | Status code, Duration |
+
+**Example:**
+```
+|CALLOUT_EXTERNAL_ENTRY|[89]|https://api.example.com/endpoint
+|CALLOUT_EXTERNAL_EXIT|[200]|[1500ms]
+```
+
+### Heap Events
+
+| Event | Description | Importance |
+|-------|-------------|------------|
+| `HEAP_ALLOCATE` | Heap allocation | Track large allocations |
+| `HEAP_DEALLOCATE` | Heap freed | Garbage collection |
+
+---
+
+## Log Levels
+
+### Categories and Levels
+
+| Category | What It Controls |
+|----------|------------------|
+| Database | SOQL, SOSL, DML |
+| Workflow | Workflow rules, Process Builder |
+| Validation | Validation rules |
+| Callout | HTTP callouts |
+| Apex Code | Apex execution |
+| Apex Profiling | Method timing |
+| Visualforce | VF page execution |
+| System | System operations |
+
+### Level Values
+
+| Level | Amount of Detail | Use Case |
+|-------|------------------|----------|
+| NONE | Nothing | Disable category |
+| ERROR | Errors only | Production monitoring |
+| WARN | Warnings + errors | |
+| INFO | General info | Default |
+| DEBUG | Detailed debug | Development |
+| FINE | Very detailed | Deep debugging |
+| FINER | Method entry/exit | Performance analysis |
+| FINEST | Everything | Complete trace |
+
+### Recommended Debug Level Settings
+
+**For Performance Issues:**
+```
+Apex Code: FINE
+Apex Profiling: FINEST
+Database: FINE
+System: DEBUG
+```
+
+**For Exception Debugging:**
+```
+Apex Code: DEBUG
+Apex Profiling: FINE
+Database: INFO
+System: DEBUG
+```
+
+**For Callout Issues:**
+```
+Apex Code: DEBUG
+Callout: FINEST
+System: DEBUG
+```
+
+---
+
+## Governor Limits Reference
+
+### Synchronous Limits
+
+| Limit | Value | Log Event |
+|-------|-------|-----------|
+| SOQL Queries | 100 | `SOQL_QUERIES` |
+| SOQL Rows | 50,000 | `SOQL_ROWS` |
+| DML Statements | 150 | `DML_STATEMENTS` |
+| DML Rows | 10,000 | `DML_ROWS` |
+| CPU Time | 10,000 ms | `CPU_TIME` |
+| Heap Size | 6 MB | `HEAP_SIZE` |
+| Callouts | 100 | `CALLOUTS` |
+| Future Calls | 50 | `FUTURE_CALLS` |
+
+### Asynchronous Limits
+
+| Limit | Value | Applies To |
+|-------|-------|------------|
+| CPU Time | 60,000 ms | @future, Batch, Queueable |
+| Heap Size | 12 MB | @future, Batch, Queueable |
+
+### Warning Thresholds
+
+| Limit | Warning (80%) | Critical (95%) |
+|-------|---------------|----------------|
+| SOQL Queries | 80 | 95 |
+| DML Statements | 120 | 143 |
+| CPU Time | 8,000 ms | 9,500 ms |
+| Heap Size | 4.8 MB | 5.7 MB |
+
+---
+
+## Common Log Patterns
+
+### Pattern 1: SOQL in Loop
+
+```
+|LOOP_BEGIN|
+|ITERATION_BEGIN|
+|SOQL_EXECUTE_BEGIN|[45]|SELECT Id FROM Contact WHERE AccountId = '001xxx'
+|SOQL_EXECUTE_END|[1 rows]
+|ITERATION_END|
+|ITERATION_BEGIN|
+|SOQL_EXECUTE_BEGIN|[45]|SELECT Id FROM Contact WHERE AccountId = '001yyy'
+|SOQL_EXECUTE_END|[1 rows]
+|ITERATION_END|
+... (repeats 100 times)
+|LIMIT_USAGE|SOQL_QUERIES|100|100  ← LIMIT HIT!
+|FATAL_ERROR|System.LimitException: Too many SOQL queries: 101
+```
+
+### Pattern 2: DML in Loop
+
+```
+|LOOP_BEGIN|
+|ITERATION_BEGIN|
+|DML_BEGIN|[78]|Op:Insert|Type:Contact|
+|DML_END|[1 rows]
+|ITERATION_END|
+... (repeats 150 times)
+|LIMIT_USAGE|DML_STATEMENTS|150|150  ← LIMIT HIT!
+|FATAL_ERROR|System.LimitException: Too many DML statements: 151
+```
+
+### Pattern 3: Non-Selective Query
+
+```
+|SOQL_EXECUTE_BEGIN|[23]|SELECT Id FROM Lead WHERE Status = 'Open'
+|SOQL_EXECUTE_END|[250000 rows]  ← Large result set!
+```
+
+### Pattern 4: CPU Limit Approaching
+
+```
+|CUMULATIVE_LIMIT_USAGE|
+|CPU_TIME|9500|10000  ← 95% used!
+```
+
+### Pattern 5: Null Pointer Exception
+
+```
+|SOQL_EXECUTE_BEGIN|[45]|SELECT Id FROM Account WHERE Id = '001xxx'
+|SOQL_EXECUTE_END|[0 rows]  ← No results!
+|METHOD_EXIT|getAccount|
+|EXCEPTION_THROWN|[47]|System.NullPointerException|Attempt to de-reference a null object
+```
+
+---
+
+## Log Analysis Checklist
+
+### Quick Scan
+
+1. **Search for `FATAL_ERROR`** - Find the exception
+2. **Search for `LIMIT_USAGE`** - Check governor limits
+3. **Search for `SOQL_EXECUTE_BEGIN`** - Count queries
+4. **Search for `DML_BEGIN`** - Count DML operations
+5. **Search for `LOOP_BEGIN`** - Check for operations in loops
+
+### Deep Analysis
+
+1. **Trace the call stack** - Use `CODE_UNIT_STARTED` events
+2. **Find the hotspot** - Use `Apex Profiling: FINEST` for method timing
+3. **Identify large queries** - Look for `[N rows]` in SOQL_EXECUTE_END
+4. **Check callout timing** - Look for slow `CALLOUT_EXTERNAL_EXIT`
+5. **Monitor heap growth** - Track `HEAP_ALLOCATE` events
+
+---
+
+## Related Commands
+
+| Command | Purpose |
+|---------|---------|
+| `sf apex list log` | List available logs |
+| `sf apex get log --log-id XXX` | Download specific log |
+| `sf apex tail log` | Stream logs real-time |
+| `sf data delete record --sobject ApexLog --record-id <id>` | Delete individual log record |
+
+See [cli-commands.md](./cli-commands.md) for detailed command reference.

package/skills/debugging-apex-logs/references/log-analysis-tools.md

@@ -0,0 +1,248 @@
+<!-- Parent: debugging-apex-logs/SKILL.md -->
+# Log Analysis Tools
+
+This guide covers tools for analyzing Salesforce debug logs, with a focus on performance profiling and bottleneck identification.
+
+---
+
+## Recommended: Apex Log Analyzer (VS Code)
+
+The **Apex Log Analyzer** is a free VS Code extension that provides visual analysis of Apex debug logs.
+
+### Installation
+
+```
+1. Open VS Code
+2. Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
+3. Search "Apex Log Analyzer"
+4. Install "Apex Log Analyzer" by FinancialForce
+```
+
+Or install via command line:
+```bash
+code --install-extension FinancialForce.lana
+```
+
+### Key Features
+
+| Feature | Description | Use Case |
+|---------|-------------|----------|
+| **Flame Charts** | Visual execution timeline | Find slow methods at a glance |
+| **Call Tree** | Hierarchical method calls | Trace execution paths |
+| **Database Analysis** | SOQL/DML highlighting | Find query hotspots |
+| **Timeline View** | Execution over time | See parallel operations |
+| **Limit Summary** | Governor limit usage | Quick health check |
+
+### How to Use
+
+1. **Get a debug log**:
+   ```bash
+   sf apex get log --log-id 07Lxx0000000000 --target-org my-sandbox -o debug.log
+   ```
+
+2. **Open in VS Code**:
+   - Open the `.log` file
+   - Click "Analyze Log" button in the editor toolbar
+   - Or use Command Palette: "Apex Log: Analyze Log"
+
+3. **Navigate the visualization**:
+   - **Flame Chart**: Wider bars = more time spent
+   - **Click methods** to see details
+   - **Hover** for exact timing
+   - **Filter** to focus on specific operations
+
+### Reading Flame Charts
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ FLAME CHART INTERPRETATION                                   │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  ████████████████████████████████████  AccountTrigger       │
+│    ██████████████████  AccountService.processAccounts       │
+│      ██████████  ← BOTTLENECK: Wide bar = slow operation    │
+│        ████  SOQL query                                      │
+│      ████████████  Another slow method                       │
+│                                                              │
+│  Time flows left → right                                     │
+│  Width = execution time                                      │
+│  Stack depth = call hierarchy                                │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Bottleneck Indicators**:
+- Wide bars at lower levels (deep in call stack)
+- Multiple identical bars (repeated operations)
+- SOQL/DML bars inside loop patterns
+
+---
+
+## SF CLI Debug Commands
+
+### List Available Logs
+
+```bash
+# List recent logs
+sf apex list log --target-org my-sandbox --json
+
+# Output includes:
+# - Log ID
+# - Start time
+# - Operation type
+# - User
+# - Size
+```
+
+### Download Logs
+
+```bash
+# Download specific log
+sf apex get log --log-id 07Lxx0000000000 --target-org my-sandbox
+
+# Save to file
+sf apex get log --log-id 07Lxx0000000000 --target-org my-sandbox > debug.log
+
+# Download with number
+sf apex get log --number 1 --target-org my-sandbox  # Most recent
+```
+
+### Real-Time Log Streaming
+
+```bash
+# Tail logs in real-time (like `tail -f`)
+sf apex tail log --target-org my-sandbox
+
+# With color highlighting
+sf apex tail log --target-org my-sandbox --color
+
+# Use an existing debug level when setting the trace flag
+sf apex tail log --target-org my-sandbox --debug-level MyDebugLevel
+
+# Skip trace flag setup when a trace flag is already configured
+sf apex tail log --target-org my-sandbox --skip-trace-flag
+```
+
+### Set Debug Level
+
+```bash
+# Create trace flag via SFDX
+sf data create record \
+  --sobject TraceFlag \
+  --values "TracedEntityId='005xx...' LogType='USER_DEBUG' StartDate='2024-01-01T00:00:00' ExpirationDate='2024-01-02T00:00:00'" \
+  --target-org my-sandbox
+```
+
+---
+
+## Manual Log Analysis (grep/ripgrep)
+
+When you need quick analysis without visual tools:
+
+### Find All SOQL Queries
+
+```bash
+# Count SOQL queries
+rg "SOQL_EXECUTE_BEGIN" debug.log | wc -l
+
+# See query text
+rg "SOQL_EXECUTE_BEGIN" debug.log
+
+# Find SOQL in loops (query appears multiple times on same line)
+rg "SOQL_EXECUTE_BEGIN" debug.log | sort | uniq -c | sort -rn | head -10
+```
+
+### Find Large Result Sets
+
+```bash
+# Find queries returning many rows
+rg "SOQL_EXECUTE_END.*\[\d{4,} rows\]" debug.log
+```
+
+### Check Governor Limits
+
+```bash
+# Find limit snapshots
+rg "LIMIT_USAGE" debug.log | tail -20
+
+# Find approaching limits (>80%)
+rg "CPU_TIME" debug.log | tail -5
+rg "HEAP_SIZE" debug.log | tail -5
+```
+
+### Find Exceptions
+
+```bash
+# Find all exceptions
+rg "EXCEPTION_THROWN|FATAL_ERROR" debug.log
+
+# Get stack traces
+rg -A 10 "FATAL_ERROR" debug.log
+```
+
+### Find Slow Operations
+
+```bash
+# Extract all timing info
+rg "\[\d+\]ms" debug.log | sort -t'[' -k2 -rn | head -20
+```
+
+---
+
+## Developer Console Analysis
+
+For quick checks directly in Salesforce:
+
+### Query Plan Tool
+
+1. Open Developer Console
+2. Query Editor tab
+3. Click "Query Plan" checkbox
+4. Run your query
+5. Review selectivity and cost
+
+### Log Inspector
+
+1. Open Developer Console
+2. Debug → Open Execute Anonymous Window
+3. Run code to generate log
+4. Select log in "Logs" tab
+5. Debug → View Log Panels
+
+**Useful Panels**:
+- **Execution Overview**: Summary of operations
+- **Timeline**: Visual execution flow
+- **Stack Tree**: Call hierarchy
+- **Database**: SOQL/DML details
+
+---
+
+## Quick Reference: What to Look For
+
+| Problem | What to Search | Pattern |
+|---------|----------------|---------|
+| SOQL in Loop | `SOQL_EXECUTE_BEGIN` | Same query repeated many times |
+| DML in Loop | `DML_BEGIN` | Same DML repeated many times |
+| Slow Query | `SOQL_EXECUTE_END` | Large row count |
+| CPU Issue | `CPU_TIME` | Approaching 10,000ms |
+| Heap Issue | `HEAP_SIZE` | Approaching 6,000,000 |
+| Exception | `EXCEPTION_THROWN` | Stack trace |
+
+---
+
+## Comparison: Analysis Tools
+
+| Tool | Pros | Cons | Best For |
+|------|------|------|----------|
+| **Apex Log Analyzer** | Visual, free, flame charts | Requires VS Code | Deep performance analysis |
+| **Developer Console** | Built-in, no install | Limited visualization | Quick checks |
+| **SF CLI + grep** | Scriptable, fast | No visualization | CI/CD, automation |
+| **Salesforce Inspector** | Browser-based | Limited log analysis | Quick org exploration |
+
+---
+
+## Related Resources
+
+- [debug-log-reference.md](./debug-log-reference.md) - Log event types
+- [benchmarking-guide.md](./benchmarking-guide.md) - Performance testing
+- [cli-commands.md](./cli-commands.md) - SF CLI reference

package/skills/debugging-apex-logs/references/scoring-rubric.md

@@ -0,0 +1,21 @@
+# Debug Analysis Scoring Rubric
+
+## 100-point rubric
+
+| Category | Points | What good looks like |
+|---|---:|---|
+| Root-cause accuracy | 25 | Finds the actual cause, not just symptoms |
+| Fix quality | 25 | Recommends a fix that directly addresses the cause |
+| Performance impact | 20 | Improves limits / efficiency without introducing regressions |
+| Completeness | 15 | Captures related issues and secondary risks |
+| Clarity | 15 | Gives an explanation the user can act on quickly |
+
+## Thresholds
+
+| Score | Rating | Meaning |
+|---|---|---|
+| 90–100 | Excellent | Expert analysis with strong fixes |
+| 80–89 | Good | Reliable analysis with minor gaps |
+| 70–79 | Acceptable | Usable, but may miss secondary issues |
+| 60–69 | Weak | Partial diagnosis only |
+| < 60 | Incomplete | Needs more investigation |

package/skills/deploying-metadata/CREDITS.md

@@ -0,0 +1,25 @@
+# Credits & Acknowledgments
+
+This skill is built on established Salesforce DevOps practices, official platform tooling, and the collective knowledge embedded in Salesforce's documentation and developer ecosystem.
+
+---
+
+## Key Concepts
+
+### Two-Phase Deployment Pattern
+The `--dry-run` validation before actual deployment is a community-established best practice to prevent production failures, widely promoted across official Salesforce documentation.
+
+### Quick Deploy Strategy
+The workflow of validating with tests, then using quick deploy for actual deployment, originates from Salesforce release management best practices.
+
+### Test Level Recommendations
+The guidance on appropriate test levels (RunLocalTests vs RunAllTests vs RunSpecifiedTests) comes from official Salesforce deployment documentation.
+
+### Incremental Deployment Strategy
+The recommendation for small, frequent deployments over large batches is a DevOps industry best practice adapted for Salesforce.
+
+---
+
+## Special Thanks
+
+To the entire Salesforce DevOps community — release managers, architects, developers, and CI/CD engineers — for continuously improving deployment practices and making Salesforce deployments more reliable.