@salesforce/afv-skills 1.8.0 → 1.9.0

package/skills/connecting-datacloud/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: connecting-datacloud
+description: "Salesforce Data Cloud Connect phase. Use this skill when the user manages Data Cloud connections, connectors, or sets up a new source system. TRIGGER when: user manages Data Cloud connections, connectors, connector metadata, tests a connection, browses source objects or databases, or sets up a new source system. DO NOT TRIGGER when: the task is about data streams or DLOs (use preparing-datacloud), DMOs or identity resolution (use harmonizing-datacloud), retrieval/search (use retrieving-datacloud), or STDM telemetry (use observing-agentforce)."
+license: MIT
+compatibility: "Requires the sf data360 CLI plugin and a Data Cloud-enabled org"
+metadata:
+  version: "1.0"
+---
+
+# connecting-datacloud: Data Cloud Connect Phase
+
+Use this skill when the user needs **source connection work**: connector discovery, connection metadata, connection testing, source-object browsing, connector schema inspection, or connector-specific setup payloads for external sources.
+
+## When This Skill Owns the Task
+
+Use `connecting-datacloud` when the work involves:
+- `sf data360 connection *`
+- connector catalog inspection
+- connection creation, update, test, or delete
+- browsing source objects, fields, databases, or schemas
+- identifying connector types already in use
+- preparing connector definitions for Snowflake, SharePoint Unstructured, or Ingestion API sources
+
+Delegate elsewhere when the user is:
+- creating data streams or DLOs → [preparing-datacloud](../preparing-datacloud/SKILL.md)
+- creating DMOs, mappings, IR rulesets, or data graphs → [harmonizing-datacloud](../harmonizing-datacloud/SKILL.md)
+- writing Data Cloud SQL or search-index workflows → [retrieving-datacloud](../retrieving-datacloud/SKILL.md)
+
+---
+
+## Required Context to Gather First
+
+Ask for or infer:
+- target org alias
+- connector type or source system
+- whether the user wants inspection only or live mutation
+- connection name or ID if one already exists
+- whether credentials are already configured outside the CLI
+- whether the user also expects stream creation right after connection setup
+- whether the source is a database, an unstructured document source, or an Ingestion API feed
+
+---
+
+## Core Operating Rules
+
+- Verify the plugin runtime first; see [../orchestrating-datacloud/references/plugin-setup.md](../orchestrating-datacloud/references/plugin-setup.md).
+- Run the shared readiness classifier before mutating connections: `node ~/.claude/skills/orchestrating-datacloud/scripts/diagnose-org.mjs -o <org> --phase connect --json`.
+- Prefer read-only discovery before connection creation.
+- Suppress linked-plugin warning noise with `2>/dev/null` for standard usage.
+- Remember that `connection list` requires `--connector-type`.
+- For `connection test`, pass `--connector-type` when resolving a non-Salesforce connection by name.
+- Discover existing connector types from streams first when the org is unfamiliar.
+- Use curated example payloads before inventing connector-specific credentials or parameters.
+- For connector types outside the curated examples, inspect a known-good UI-created connection via REST before building JSON.
+- Do not promise API-based stream creation for every connector type just because connection creation succeeds.
+
+---
+
+## Recommended Workflow
+
+### 1. Classify readiness for connect work
+```bash
+node ~/.claude/skills/orchestrating-datacloud/scripts/diagnose-org.mjs -o <org> --phase connect --json
+```
+
+### 2. Discover connector types
+```bash
+sf data360 connection connector-list -o <org> 2>/dev/null
+sf data360 data-stream list -o <org> 2>/dev/null
+```
+
+### 3. Inspect connections by type
+```bash
+sf data360 connection list -o <org> --connector-type SalesforceDotCom 2>/dev/null
+sf data360 connection list -o <org> --connector-type REDSHIFT 2>/dev/null
+sf data360 connection list -o <org> --connector-type SNOWFLAKE 2>/dev/null
+```
+
+### 4. Inspect a specific connection or uploaded schema
+```bash
+sf data360 connection get -o <org> --name <connection> 2>/dev/null
+sf data360 connection objects -o <org> --name <connection> 2>/dev/null
+sf data360 connection fields -o <org> --name <connection> 2>/dev/null
+sf data360 connection schema-get -o <org> --name <connection-id> 2>/dev/null
+```
+
+### 5. Test or create only after discovery
+```bash
+sf data360 connection test -o <org> --name <connection> --connector-type <type> 2>/dev/null
+sf data360 connection create -o <org> -f connection.json 2>/dev/null
+```
+
+### 6. Start from curated example payloads for external connectors
+Use the phase-owned examples before inventing a payload from scratch:
+- `examples/connections/heroku-postgres.json`
+- `examples/connections/redshift.json`
+- `examples/connections/sharepoint-unstructured.json`
+- `examples/connections/snowflake-connection.json`
+- `examples/connections/ingest-api-connection.json`
+- `examples/connections/ingest-api-schema.json`
+
+Typical Ingestion API setup flow:
+```bash
+sf data360 connection create -o <org> -f examples/connections/ingest-api-connection.json 2>/dev/null
+sf data360 connection schema-upsert -o <org> --name <connector-id> -f examples/connections/ingest-api-schema.json 2>/dev/null
+sf data360 connection schema-get -o <org> --name <connector-id> 2>/dev/null
+```
+
+### 7. Discover payload fields for unknown connector types
+Create one in the UI, then inspect it directly:
+```bash
+sf api request rest "/services/data/v66.0/ssot/connections/<id>" -o <org>
+```
+
+---
+
+## High-Signal Gotchas
+
+- `connection list` has no true global "list all" mode; query by connector type.
+- The connector catalog name and connection connector type are not always the same label.
+- `connection test` may need `--connector-type` for name resolution when the source is not a default Salesforce connector.
+- An empty connection list usually means "enabled but not configured yet", not "feature disabled".
+- Heroku Postgres, Redshift, Snowflake, SharePoint Unstructured, and Ingestion API all use different credential and parameter shapes; reuse the curated examples instead of guessing.
+- SharePoint Unstructured uses `clientId`, `clientSecret`, and `tokenEndpoint` in the `credentials` array and does not require a `parameters` array.
+- Snowflake uses key-pair auth and can often be created through the API, but downstream stream creation can still remain UI-only.
+- Ingestion API connector setup is incomplete until `connection schema-upsert` has uploaded the object schema.
+- Some external connector credential setup still depends on UI-side configuration or external-system permissions.
+
+---
+
+## Output Format
+
+```text
+Connect task: <inspect / create / test / update>
+Connector type: <SalesforceDotCom / REDSHIFT / SNOWFLAKE / SPUnstructuredDocument / IngestApi / ...>
+Target org: <alias>
+Commands: <key commands run>
+Verification: <passed / partial / blocked>
+Next step: <prepare phase or connector follow-up>
+```
+
+---
+
+## References
+
+- [README.md](README.md)
+- [examples/connections/heroku-postgres.json](examples/connections/heroku-postgres.json)
+- [examples/connections/redshift.json](examples/connections/redshift.json)
+- [examples/connections/sharepoint-unstructured.json](examples/connections/sharepoint-unstructured.json)
+- [examples/connections/snowflake-connection.json](examples/connections/snowflake-connection.json)
+- [examples/connections/ingest-api-connection.json](examples/connections/ingest-api-connection.json)
+- [examples/connections/ingest-api-schema.json](examples/connections/ingest-api-schema.json)
+- [../orchestrating-datacloud/references/plugin-setup.md](../orchestrating-datacloud/references/plugin-setup.md)
+- [../orchestrating-datacloud/references/feature-readiness.md](../orchestrating-datacloud/references/feature-readiness.md)
+- [../orchestrating-datacloud/UPSTREAM.md](../orchestrating-datacloud/UPSTREAM.md)

package/skills/connecting-datacloud/examples/connections/heroku-postgres.json

@@ -0,0 +1,15 @@
+{
+  "connectorType": "HerokuPostgres",
+  "label": "My Heroku DB",
+  "name": "My_Heroku_DB",
+  "method": "Ingress",
+  "credentials": [
+    { "paramName": "credentialType", "value": "UsernamePasswordAuthentication" },
+    { "paramName": "user", "value": "<HEROKU_DB_USER>" },
+    { "paramName": "password", "value": "<HEROKU_DB_PASSWORD>" }
+  ],
+  "parameters": [
+    { "paramName": "jdbc_connection_url", "value": "<HOST>:<PORT>" },
+    { "paramName": "DATABASE", "value": "<DATABASE_NAME>" }
+  ]
+}

package/skills/connecting-datacloud/examples/connections/ingest-api-connection.json

@@ -0,0 +1,5 @@
+{
+  "connectorType": "IngestApi",
+  "label": "<CONNECTOR_LABEL>",
+  "name": "<CONNECTOR_NAME>"
+}

package/skills/connecting-datacloud/examples/connections/ingest-api-schema.json

@@ -0,0 +1,31 @@
+{
+  "schemas": [
+    {
+      "label": "<OBJECT_NAME>",
+      "name": "<OBJECT_NAME>",
+      "schemaType": "IngestApi",
+      "fields": [
+        {
+          "name": "Id",
+          "label": "Id",
+          "dataType": "Text"
+        },
+        {
+          "name": "Name",
+          "label": "Name",
+          "dataType": "Text"
+        },
+        {
+          "name": "Timestamp",
+          "label": "Timestamp",
+          "dataType": "DateTime"
+        },
+        {
+          "name": "Value",
+          "label": "Value",
+          "dataType": "Number"
+        }
+      ]
+    }
+  ]
+}

package/skills/connecting-datacloud/examples/connections/redshift.json

@@ -0,0 +1,16 @@
+{
+  "connectorType": "REDSHIFT",
+  "label": "My Redshift",
+  "name": "My_Redshift",
+  "method": "Ingress",
+  "credentials": [
+    { "paramName": "authenticationOption", "value": "usernameAndPassword" },
+    { "paramName": "username", "value": "<REDSHIFT_USER>" },
+    { "paramName": "password", "value": "<REDSHIFT_PASSWORD>" }
+  ],
+  "parameters": [
+    { "paramName": "url", "value": "<HOST>:<PORT>" },
+    { "paramName": "database", "value": "<DATABASE_NAME>" },
+    { "paramName": "hasPrivateNetworkRoute", "value": "false" }
+  ]
+}

package/skills/connecting-datacloud/examples/connections/sharepoint-unstructured.json

@@ -0,0 +1,20 @@
+{
+  "connectorType": "SPUnstructuredDocument",
+  "label": "My SharePoint Docs",
+  "name": "My_SharePoint_Docs",
+  "method": "Ingress",
+  "credentials": [
+    {
+      "paramName": "clientId",
+      "value": "<AZURE_APP_CLIENT_ID>"
+    },
+    {
+      "paramName": "clientSecret",
+      "value": "<AZURE_APP_CLIENT_SECRET>"
+    },
+    {
+      "paramName": "tokenEndpoint",
+      "value": "https://login.microsoftonline.com/<AZURE_TENANT_ID>/oauth2/v2.0/token"
+    }
+  ]
+}

package/skills/connecting-datacloud/examples/connections/snowflake-connection.json

@@ -0,0 +1,42 @@
+{
+  "connectorType": "SNOWFLAKE",
+  "label": "Snowflake Demo",
+  "name": "Snowflake_Demo",
+  "method": "Ingress",
+  "credentials": [
+    {
+      "paramName": "credentialType",
+      "value": "KeyPairAuthentication"
+    },
+    {
+      "paramName": "user",
+      "value": "<SNOWFLAKE_USERNAME>"
+    },
+    {
+      "paramName": "privateKey",
+      "value": "<YOUR_PRIVATE_KEY_WITHOUT_BEGIN_END_HEADERS>"
+    }
+  ],
+  "parameters": [
+    {
+      "paramName": "accountUrl",
+      "value": "https://<ORG_ID>-<ACCOUNT_ID>.snowflakecomputing.com"
+    },
+    {
+      "paramName": "database",
+      "value": "<DATABASE_NAME>"
+    },
+    {
+      "paramName": "warehouse",
+      "value": "<WAREHOUSE_NAME>"
+    },
+    {
+      "paramName": "region",
+      "value": "<AWS_REGION>"
+    },
+    {
+      "paramName": "hasPrivateNetworkRoute",
+      "value": "false"
+    }
+  ]
+}

package/skills/debugging-apex-logs/CREDITS.md

@@ -0,0 +1,22 @@
+# Credits & Acknowledgments
+
+This skill is built on Salesforce's official Apex debugging documentation and established Apex performance patterns. The benchmarking techniques, governor limit patterns, and optimization approaches incorporated here reflect current Apex development best practices.
+
+---
+
+## Key Patterns
+
+### Governor Limit Awareness
+Governor limit values, debug log event types, and the Apex execution model are defined by the Salesforce platform and reflected in `references/debug-log-reference.md`.
+
+### Debug Log Specifications
+Log event specifications, log level definitions, and format documentation are based on official Apex debug log behavior and integrated into `references/debug-log-reference.md`.
+
+### Benchmarking Patterns
+String-building performance characteristics, loop iteration comparisons, and data structure lookup benchmarks reflect well-established Apex optimization techniques adapted into the reusable templates in this skill.
+
+---
+
+## License
+
+MIT licensed. See the LICENSE file for complete terms.

package/skills/debugging-apex-logs/README.md

@@ -0,0 +1,74 @@
+# debugging-apex-logs
+
+Salesforce debugging and troubleshooting skill with log analysis, governor limit detection, and agentic fix suggestions. Identify performance bottlenecks and automatically suggest fixes.
+
+## Features
+
+- **Log Analysis**: Parse and analyze Apex debug logs
+- **Governor Limit Detection**: SOQL, DML, CPU, and heap limit monitoring
+- **Performance Analysis**: Find slow queries and expensive operations
+- **Stack Trace Interpretation**: Parse exceptions and identify root causes
+- **Agentic Fix Suggestions**: Automatically suggest code fixes
+- **100-Point Scoring**: Issue severity classification
+
+
+## Quick Start
+
+### 1. Invoke the skill
+
+```
+Skill: debugging-apex-logs
+Request: "Analyze debug logs for AccountTrigger performance issues in org dev"
+```
+
+### 2. Common operations
+
+| Operation | Example Request |
+|-----------|-----------------|
+| Analyze log | "Analyze the latest debug log for errors" |
+| List logs | "Show recent debug logs for org dev" |
+| Tail logs | "Tail logs for user admin@company.com" |
+| Find limits | "Find governor limit issues in the log" |
+| Query plan | "Analyze query plan for Account SOQL" |
+
+## Log Commands
+
+```bash
+# List recent logs
+sf apex list log --target-org [alias] --json
+
+# Get specific log
+sf apex get log --log-id 07Lxx0000000000 --target-org [alias]
+
+# Tail logs real-time
+sf apex tail log --target-org [alias] --color
+```
+
+## Scoring System (100 Points)
+
+| Category | Points | Focus |
+|----------|--------|-------|
+| Governor Limits | 25 | SOQL, DML, CPU, Heap analysis |
+| Performance | 25 | Query optimization, N+1 detection |
+| Error Analysis | 20 | Exception handling, stack traces |
+| Root Cause | 20 | Issue identification, fix suggestions |
+| Documentation | 10 | Clear explanations, actionable fixes |
+
+## Cross-Skill Integration
+
+| Related Skill | When to Use |
+|---------------|-------------|
+| sf-apex | Fix identified Apex issues |
+| querying-soql | Optimize slow SOQL queries |
+| running-apex-tests | Re-run tests after fixes |
+
+## Documentation
+
+- [Benchmarking Guide](references/benchmarking-guide.md)
+
+
+## Requirements
+
+- sf CLI v2
+- Target Salesforce org
+- Debug logs enabled for target user

package/skills/debugging-apex-logs/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: debugging-apex-logs
+description: "Salesforce debug log analysis and troubleshooting with 100-point scoring. TRIGGER when: user analyzes debug logs, hits governor limits, reads stack traces, or touches .log files from Salesforce orgs. DO NOT TRIGGER when: running Apex tests (use running-apex-tests), generating or fixing Apex code (use generating-apex), or Agentforce session tracing (use observing-agentforce)."
+license: MIT
+metadata:
+  version: "1.1"
+---
+
+# debugging-apex-logs: Salesforce Debug Log Analysis & Troubleshooting
+
+Use this skill when the user needs **root-cause analysis from debug logs**: governor-limit diagnosis, stack-trace interpretation, slow-query investigation, heap / CPU pressure analysis, or a reproduction-to-fix loop based on log evidence.
+
+## When This Skill Owns the Task
+
+Use `debugging-apex-logs` when the work involves:
+- `.log` files from Salesforce
+- stack traces and exception analysis
+- governor limits
+- SOQL / DML / CPU / heap troubleshooting
+- query-plan or performance evidence extracted from logs
+
+Delegate elsewhere when the user is:
+- running or repairing Apex tests → [running-apex-tests](../running-apex-tests/SKILL.md)
+- generating or implementing the code fix → [generating-apex](../generating-apex/SKILL.md)
+- debugging Agentforce session traces / parquet telemetry → [observing-agentforce](../observing-agentforce/SKILL.md)
+
+---
+
+## Required Context to Gather First
+
+Ask for or infer:
+- org alias
+- failing transaction / user flow / test name
+- approximate timestamp or transaction window
+- user / record / request ID if known
+- whether the goal is diagnosis only or diagnosis + fix loop
+
+---
+
+## Recommended Workflow
+
+### 1. Retrieve logs
+
+Use the commands in [references/cli-commands.md](references/cli-commands.md) to list, download, or stream logs for the target org.
+
+### 2. Analyze in this order
+1. entry point and transaction type
+2. exceptions / fatal errors
+3. governor limits
+4. repeated SOQL / DML patterns
+5. CPU / heap hotspots
+6. callout timing and external failures
+
+### 3. Classify severity
+- **Critical** — runtime failure, hard limit, corruption risk
+- **Warning** — near-limit, non-selective query, slow path
+- **Info** — optimization opportunity or hygiene issue
+
+### 4. Recommend the smallest correct fix
+Prefer fixes that are:
+- root-cause oriented
+- bulk-safe
+- testable
+- easy to verify with a rerun
+
+Expanded workflow: [references/analysis-playbook.md](references/analysis-playbook.md)
+
+---
+
+## High-Signal Issue Patterns
+
+| Issue | Primary signal | Default fix direction |
+|---|---|---|
+| SOQL in loop | repeating `SOQL_EXECUTE_BEGIN` in a repeated call path | query once, use maps / grouped collections |
+| DML in loop | repeated `DML_BEGIN` patterns | collect rows, bulk DML once |
+| Non-selective query | high rows scanned / poor selectivity | add indexed filters, reduce scope |
+| CPU pressure | CPU usage approaching sync limit | reduce algorithmic complexity, cache, async where valid |
+| Heap pressure | heap usage approaching sync limit | stream with SOQL for-loops, reduce in-memory data |
+| Null pointer / fatal error | `EXCEPTION_THROWN` / `FATAL_ERROR` | guard null assumptions, fix empty-query handling |
+
+Expanded examples: [references/common-issues.md](references/common-issues.md)
+
+---
+
+## Output Format
+
+When finishing analysis, report in this order:
+
+1. **What failed**
+2. **Where it failed** (class / method / line / transaction stage)
+3. **Why it failed** (root cause, not just symptom)
+4. **How severe it is**
+5. **Recommended fix**
+6. **Verification step**
+
+Suggested shape:
+
+```text
+Issue: <summary>
+Location: <class / line / transaction>
+Root cause: <explanation>
+Severity: Critical | Warning | Info
+Fix: <specific action>
+Verify: <test or rerun step>
+```
+
+---
+
+## Rules / Constraints
+
+| Rule | Rationale |
+|------|-----------|
+| Always base fix recommendations on log evidence | Avoid speculative diagnosis — root cause must be traceable in the log |
+| Report all six output fields for every issue found | Ensures actionable, complete findings for each problem |
+| Classify every finding as Critical, Warning, or Info | Helps the user prioritize which issues to address first |
+| Delegate code generation to `generating-apex` | This skill diagnoses; it does not rewrite Apex code |
+| Delegate test execution to `running-apex-tests` | This skill does not run or repair test classes |
+| Never assume limits are safe without reading `LIMIT_USAGE` events | Limits may be consumed by earlier operations not visible in the failure point |
+
+---
+
+## Gotchas
+
+| Pitfall | Resolution |
+|---------|------------|
+| Log truncated at 2 MB | Reduce debug levels (e.g., `ApexCode: INFO`, `ApexProfiling: FINE`) and re-capture |
+| Same issue appears as both SOQL and CPU problem | Fix SOQL-in-loop first — it typically drives the CPU spike as a secondary effect |
+| No logs appear after trace flag is set | Verify the trace flag `ExpirationDate` is in the future and the correct user is traced |
+| Async context changes limit values | CPU limit is 60,000 ms async vs 10,000 ms sync — check transaction type before flagging limits |
+| Stack trace points to framework line, not user code | Walk up the call stack past trigger handlers to find the originating user code |
+
+---
+
+## Cross-Skill Integration
+
+| Need | Delegate to | Reason |
+|---|---|---|
+| Implement Apex fix | [generating-apex](../generating-apex/SKILL.md) | code change generation / review |
+| Reproduce via tests | [running-apex-tests](../running-apex-tests/SKILL.md) | test execution and coverage loop |
+| Deploy fix | [deploying-metadata](../deploying-metadata/SKILL.md) | deployment orchestration |
+| Create debugging data | [handling-sf-data](../handling-sf-data/SKILL.md) | targeted seed / repro data |
+
+---
+
+## Reference File Index
+
+| File | When to read |
+|------|-------------|
+| `references/analysis-playbook.md` | Start here — expanded step-by-step workflow for any debugging session |
+| `references/common-issues.md` | Quick lookup for SOQL in loop, DML in loop, CPU/heap pressure, null pointer patterns |
+| `references/cli-commands.md` | SF CLI commands for retrieving, streaming, and managing debug logs |
+| `references/debug-log-reference.md` | Full event type catalog, log levels, and governor limit reference values |
+| `references/log-analysis-tools.md` | Tool guide: Apex Log Analyzer, Developer Console, CLI grep patterns |
+| `references/benchmarking-guide.md` | Performance benchmarking techniques, benchmark data, and anti-patterns |
+| `references/scoring-rubric.md` | 100-point scoring rubric for evaluating analysis quality |
+| `assets/benchmarking-template.cls` | Copy-paste Anonymous Apex template for running performance benchmarks |
+| `assets/cpu-heap-optimization.cls` | Apex patterns for reducing CPU time and heap allocation |
+| `assets/dml-in-loop-fix.cls` | Before/after example for resolving DML-in-loop violations |
+| `assets/soql-in-loop-fix.cls` | Before/after example for resolving SOQL-in-loop violations |
+| `assets/null-pointer-fix.cls` | Patterns for guarding against null pointer exceptions |
+
+---
+
+## Score Guide
+
+| Score | Meaning |
+|---|---|
+| 90+ | Expert analysis with strong fix guidance |
+| 80–89 | Good analysis with minor gaps |
+| 70–79 | Acceptable but may miss secondary issues |
+| 60–69 | Partial diagnosis only |
+| < 60 | Incomplete analysis |