@salesforce/afv-skills 1.22.0 → 1.23.0

package/skills/querying-soql/SKILL.md

@@ -1,142 +0,0 @@
----
-name: querying-soql
-description: "SOQL query generation, optimization, and analysis with 100-point scoring. Use this skill when the user needs SOQL/SOSL authoring or optimization: natural-language-to-query generation, relationship queries, aggregates, query-plan analysis, and performance or safety improvements for Salesforce queries. TRIGGER when: user writes, optimizes, or debugs SOQL/SOSL queries, touches .soql files, or asks about relationship queries, aggregates, or query performance. DO NOT TRIGGER when: bulk data operations (use handling-sf-data), Apex DML logic (use generating-apex), or report/dashboard queries."
-metadata:
-  version: "1.1"
----
-
-# querying-soql: Salesforce SOQL Query Expert
-
-Use this skill when the user needs **SOQL/SOSL authoring or optimization**: natural-language-to-query generation, relationship queries, aggregates, query-plan analysis, and performance/safety improvements for Salesforce queries.
-
-## When This Skill Owns the Task
-
-Use `querying-soql` when the work involves:
-- `.soql` files
-- query generation from natural language
-- relationship queries and aggregate queries
-- query optimization and selectivity analysis
-- SOQL/SOSL syntax and governor-aware design
-
-Delegate elsewhere when the user is:
-- performing bulk data operations → [handling-sf-data](../handling-sf-data/SKILL.md)
-- embedding query logic inside broader Apex implementation → [generating-apex](../generating-apex/SKILL.md)
-- debugging via logs rather than query shape → [debugging-apex-logs](../debugging-apex-logs/SKILL.md)
-
----
-
-## Required Context to Gather First
-
-Ask for or infer:
-- target object(s)
-- fields needed
-- filter criteria
-- sort / limit requirements
-- whether the query is for display, automation, reporting-like analysis, or Apex usage
-- whether performance / selectivity is already a concern
-
----
-
-## Recommended Workflow
-
-### 1. Generate the simplest correct query
-Prefer:
-- only needed fields
-- clear WHERE criteria
-- reasonable LIMIT when appropriate
-- relationship depth only as deep as necessary
-
-### 2. Choose the right query shape
-| Need | Default pattern |
-|---|---|
-| parent data from child | child-to-parent traversal |
-| child rows from parent | subquery |
-| counts / rollups | aggregate query |
-| records with / without related rows | semi-join / anti-join |
-| text search across objects | SOSL |
-
-### 3. Optimize for selectivity and safety
-Check:
-- indexed / selective filters
-- no unnecessary fields
-- no avoidable wildcard or scan-heavy patterns
-- security enforcement expectations
-
-### 4. Validate execution path if needed
-If the user wants runtime verification, hand off execution to:
-- [handling-sf-data](../handling-sf-data/SKILL.md)
-
----
-
-## High-Signal Rules
-
-- never use `SELECT *` style thinking; query only required fields
-- do not query inside loops in Apex contexts
-- prefer filtering in SOQL rather than post-filtering in Apex
-- use aggregates for counts and grouped summaries instead of loading unnecessary records
-- evaluate wildcard usage carefully; leading wildcards often defeat indexes
-- account for security mode / field access requirements when queries move into Apex
-
----
-
-## Output Format
-
-When finishing, report in this order:
-1. **Query purpose**
-2. **Final SOQL/SOSL**
-3. **Why this shape was chosen**
-4. **Optimization or security notes**
-5. **Execution suggestion if needed**
-
-Suggested shape — use `references/soql-syntax-reference.md` for exact syntax:
-
-```
-Query goal: <summary>
-Query: <soql or sosl>
-Design: <relationship / aggregate / filter choices>
-Notes: <selectivity, limits, security, governor awareness>
-Next step: <run in handling-sf-data or embed in Apex>
-```
-
----
-
-## Cross-Skill Integration
-
-| Need | Delegate to | Reason |
-|---|---|---|
-| run the query against an org | [handling-sf-data](../handling-sf-data/SKILL.md) | execution and export |
-| embed the query in services/selectors | [generating-apex](../generating-apex/SKILL.md) | implementation context |
-| analyze slow-query symptoms from logs | [debugging-apex-logs](../debugging-apex-logs/SKILL.md) | runtime evidence |
-| wire query-backed UI | [generating-lwc-components](../generating-lwc-components/SKILL.md) | frontend integration |
-
----
-
-## Score Guide
-
-| Score | Meaning |
-|---|---|
-| 90+ | production-optimized query |
-| 80–89 | good query with minor improvements possible |
-| 70–79 | functional but performance concerns remain |
-| < 70 | needs revision before production use |
-
----
-
-## Reference File Index
-
-| File | When to read |
-|------|-------------|
-| `references/soql-syntax-reference.md` | Syntax, operators, date literals, relationship query patterns |
-| `references/query-optimization.md` | Selectivity rules, indexing strategy, governor limits, security patterns |
-| `references/soql-reference.md` | Quick reference — operators, date functions, aggregate functions, WITH clauses |
-| `references/anti-patterns.md` | Common SOQL mistakes and their fixes — read before finalizing any query |
-| `references/selector-patterns.md` | Apex selector layer patterns — read when embedding queries in Apex classes |
-| `references/field-coverage-rules.md` | Field coverage validation — read when generating SOQL used inside Apex code |
-| `references/cli-commands.md` | sf CLI query execution, bulk export, query plan commands |
-| `assets/basic-queries.soql` | Starter query examples for common objects |
-| `assets/relationship-queries.soql` | Parent-to-child and child-to-parent relationship query patterns |
-| `assets/aggregate-queries.soql` | COUNT, SUM, GROUP BY, ROLLUP query patterns |
-| `assets/optimization-patterns.soql` | Selective filter and index-aware query patterns |
-| `assets/bulkified-query-pattern.cls` | Apex Map-based bulk query pattern for trigger contexts |
-| `assets/selector-class.cls` | Full selector class implementation template |
-| `scripts/post-tool-validate.py` | Post-write hook — runs static SOQL validation and live query plan analysis after `.soql` file edits |

package/skills/querying-soql/assets/aggregate-queries.soql

@@ -1,242 +0,0 @@
-/**
- * AGGREGATE QUERY PATTERNS
- *
- * SOQL aggregate functions:
- * - COUNT(), COUNT(field), COUNT_DISTINCT(field)
- * - SUM(field), AVG(field), MIN(field), MAX(field)
- *
- * Use with GROUP BY for grouping results.
- */
-
-// ═══════════════════════════════════════════════════════════════════════════
-// BASIC COUNT
-// ═══════════════════════════════════════════════════════════════════════════
-
--- Count all records
-SELECT COUNT() FROM Account
-
--- Count with filter
-SELECT COUNT() FROM Contact WHERE Email != null
-
--- Count with field alias
-SELECT COUNT(Id) total FROM Account
-
--- Count distinct values
-SELECT COUNT_DISTINCT(Industry) FROM Account
-
-// ═══════════════════════════════════════════════════════════════════════════
-// SUM, AVG, MIN, MAX
-// ═══════════════════════════════════════════════════════════════════════════
-
--- Sum of amounts
-SELECT SUM(Amount) totalAmount FROM Opportunity WHERE IsClosed = true
-
--- Average amount
-SELECT AVG(Amount) avgAmount FROM Opportunity WHERE StageName = 'Closed Won'
-
--- Min and Max
-SELECT MIN(Amount) smallest, MAX(Amount) largest
-FROM Opportunity
-WHERE IsClosed = true
-
--- Combined aggregates
-SELECT
-    COUNT(Id) totalOpps,
-    SUM(Amount) totalAmount,
-    AVG(Amount) avgAmount,
-    MIN(Amount) minAmount,
-    MAX(Amount) maxAmount
-FROM Opportunity
-WHERE StageName = 'Closed Won'
-AND CALENDAR_YEAR(CloseDate) = 2024
-
-// ═══════════════════════════════════════════════════════════════════════════
-// GROUP BY
-// ═══════════════════════════════════════════════════════════════════════════
-
--- Count by single field
-SELECT Industry, COUNT(Id)
-FROM Account
-GROUP BY Industry
-
--- Count by multiple fields
-SELECT Industry, Type, COUNT(Id)
-FROM Account
-GROUP BY Industry, Type
-
--- Sum by category
-SELECT StageName, SUM(Amount)
-FROM Opportunity
-GROUP BY StageName
-
--- Average by owner
-SELECT OwnerId, AVG(Amount)
-FROM Opportunity
-GROUP BY OwnerId
-
--- Aggregate by date part
-SELECT CALENDAR_MONTH(CloseDate), SUM(Amount)
-FROM Opportunity
-WHERE CALENDAR_YEAR(CloseDate) = 2024
-GROUP BY CALENDAR_MONTH(CloseDate)
-ORDER BY CALENDAR_MONTH(CloseDate)
-
--- Year and Month grouping
-SELECT CALENDAR_YEAR(CloseDate) yr, CALENDAR_MONTH(CloseDate) mn, SUM(Amount)
-FROM Opportunity
-GROUP BY CALENDAR_YEAR(CloseDate), CALENDAR_MONTH(CloseDate)
-ORDER BY CALENDAR_YEAR(CloseDate), CALENDAR_MONTH(CloseDate)
-
-// ═══════════════════════════════════════════════════════════════════════════
-// HAVING CLAUSE
-// ═══════════════════════════════════════════════════════════════════════════
-
--- Filter groups by aggregate result
-SELECT Industry, COUNT(Id) cnt
-FROM Account
-GROUP BY Industry
-HAVING COUNT(Id) > 10
-
--- Multiple HAVING conditions
-SELECT OwnerId, SUM(Amount) total, COUNT(Id) cnt
-FROM Opportunity
-WHERE StageName = 'Closed Won'
-GROUP BY OwnerId
-HAVING SUM(Amount) > 100000
-AND COUNT(Id) >= 5
-
--- HAVING with different aggregate than SELECT
-SELECT LeadSource, COUNT(Id)
-FROM Lead
-GROUP BY LeadSource
-HAVING AVG(NumberOfEmployees) > 100
-
-// ═══════════════════════════════════════════════════════════════════════════
-// GROUP BY ROLLUP (Subtotals)
-// ═══════════════════════════════════════════════════════════════════════════
-
--- Single rollup
-SELECT Industry, COUNT(Id)
-FROM Account
-GROUP BY ROLLUP(Industry)
--- Returns: individual industries + grand total (null Industry row)
-
--- Multiple field rollup
-SELECT Industry, Type, COUNT(Id)
-FROM Account
-GROUP BY ROLLUP(Industry, Type)
--- Returns: Industry+Type combos, Industry subtotals, grand total
-
--- With SUM
-SELECT StageName, CALENDAR_MONTH(CloseDate), SUM(Amount)
-FROM Opportunity
-WHERE CALENDAR_YEAR(CloseDate) = 2024
-GROUP BY ROLLUP(StageName, CALENDAR_MONTH(CloseDate))
-
-// ═══════════════════════════════════════════════════════════════════════════
-// GROUP BY CUBE (All Combinations)
-// ═══════════════════════════════════════════════════════════════════════════
-
--- All dimension combinations
-SELECT Industry, Type, COUNT(Id)
-FROM Account
-GROUP BY CUBE(Industry, Type)
--- Returns: Industry+Type, Industry only, Type only, grand total
-
-// ═══════════════════════════════════════════════════════════════════════════
-// DATE FUNCTIONS IN AGGREGATES
-// ═══════════════════════════════════════════════════════════════════════════
-
--- By calendar year
-SELECT CALENDAR_YEAR(CreatedDate) yr, COUNT(Id)
-FROM Account
-GROUP BY CALENDAR_YEAR(CreatedDate)
-
--- By calendar quarter
-SELECT CALENDAR_YEAR(CloseDate), CALENDAR_QUARTER(CloseDate), SUM(Amount)
-FROM Opportunity
-GROUP BY CALENDAR_YEAR(CloseDate), CALENDAR_QUARTER(CloseDate)
-
--- By fiscal year (if fiscal year defined)
-SELECT FISCAL_YEAR(CloseDate), SUM(Amount)
-FROM Opportunity
-GROUP BY FISCAL_YEAR(CloseDate)
-
--- By week
-SELECT WEEK_IN_YEAR(CreatedDate), COUNT(Id)
-FROM Lead
-WHERE CALENDAR_YEAR(CreatedDate) = 2024
-GROUP BY WEEK_IN_YEAR(CreatedDate)
-
--- By day of week
-SELECT DAY_IN_WEEK(CreatedDate), COUNT(Id)
-FROM Case
-WHERE CreatedDate = THIS_MONTH
-GROUP BY DAY_IN_WEEK(CreatedDate)
--- 1=Sunday, 2=Monday, etc.
-
-// ═══════════════════════════════════════════════════════════════════════════
-// COMMON AGGREGATE PATTERNS
-// ═══════════════════════════════════════════════════════════════════════════
-
--- Sales by rep this year
-SELECT Owner.Name, SUM(Amount) totalSales, COUNT(Id) dealCount
-FROM Opportunity
-WHERE StageName = 'Closed Won'
-AND CloseDate = THIS_YEAR
-GROUP BY Owner.Name
-ORDER BY SUM(Amount) DESC
-
--- Lead conversion rate by source
-SELECT LeadSource, COUNT(Id) total, SUM(CASE WHEN IsConverted = true THEN 1 ELSE 0 END) converted
-FROM Lead
-GROUP BY LeadSource
--- Note: CASE not supported in SOQL. Calculate in Apex.
-
--- Cases by status and priority
-SELECT Status, Priority, COUNT(Id)
-FROM Case
-WHERE CreatedDate = THIS_MONTH
-GROUP BY Status, Priority
-
--- Average deal size by industry
-SELECT Account.Industry, AVG(Amount)
-FROM Opportunity
-WHERE StageName = 'Closed Won'
-GROUP BY Account.Industry
-HAVING AVG(Amount) > 50000
-
--- Top accounts by opportunity count
-SELECT AccountId, Account.Name, COUNT(Id) oppCount
-FROM Opportunity
-GROUP BY AccountId, Account.Name
-ORDER BY COUNT(Id) DESC
-LIMIT 20
-
--- Pipeline by stage and month
-SELECT StageName, CALENDAR_MONTH(CloseDate) closeMonth, SUM(Amount)
-FROM Opportunity
-WHERE IsClosed = false
-AND CloseDate = THIS_QUARTER
-GROUP BY StageName, CALENDAR_MONTH(CloseDate)
-ORDER BY CALENDAR_MONTH(CloseDate), StageName
-
-// ═══════════════════════════════════════════════════════════════════════════
-// AGGREGATE IN APEX
-// ═══════════════════════════════════════════════════════════════════════════
-
-/*
-// In Apex, aggregate results are returned as AggregateResult[]
-
-List<AggregateResult> results = [
-    SELECT Industry, COUNT(Id) cnt, SUM(AnnualRevenue) total
-    FROM Account
-    GROUP BY Industry
-];
-
-for (AggregateResult ar : results) {
-    String industry = (String) ar.get('Industry');
-    Integer count = (Integer) ar.get('cnt');
-    Decimal total = (Decimal) ar.get('total');
-}
-*/

package/skills/querying-soql/assets/basic-queries.soql

@@ -1,188 +0,0 @@
-/**
- * BASIC SOQL QUERY PATTERNS
- *
- * This file contains common SOQL patterns for everyday queries.
- * Each pattern includes the query and usage notes.
- */
-
-// ═══════════════════════════════════════════════════════════════════════════
-// SIMPLE SELECT QUERIES
-// ═══════════════════════════════════════════════════════════════════════════
-
--- Get accounts with specific fields
-SELECT Id, Name, Industry, AnnualRevenue, Phone
-FROM Account
-LIMIT 100
-
--- Get contacts with email
-SELECT Id, FirstName, LastName, Email, Phone
-FROM Contact
-WHERE Email != null
-LIMIT 100
-
--- Get opportunities by stage
-SELECT Id, Name, Amount, StageName, CloseDate
-FROM Opportunity
-WHERE StageName = 'Prospecting'
-ORDER BY Amount DESC
-
-// ═══════════════════════════════════════════════════════════════════════════
-// DATE FILTERING
-// ═══════════════════════════════════════════════════════════════════════════
-
--- Records created today
-SELECT Id, Name FROM Account
-WHERE CreatedDate = TODAY
-
--- Records created this week
-SELECT Id, Name FROM Lead
-WHERE CreatedDate = THIS_WEEK
-
--- Records created in last 30 days
-SELECT Id, Name, CreatedDate FROM Contact
-WHERE CreatedDate = LAST_N_DAYS:30
-ORDER BY CreatedDate DESC
-
--- Records modified this month
-SELECT Id, Name, LastModifiedDate FROM Account
-WHERE LastModifiedDate = THIS_MONTH
-
--- Opportunities closing this quarter
-SELECT Id, Name, Amount, CloseDate
-FROM Opportunity
-WHERE CloseDate = THIS_QUARTER
-AND IsClosed = false
-
--- Records created in specific date range
-SELECT Id, Name, CreatedDate FROM Account
-WHERE CreatedDate >= 2024-01-01T00:00:00Z
-AND CreatedDate < 2024-04-01T00:00:00Z
-
-// ═══════════════════════════════════════════════════════════════════════════
-// TEXT FILTERING
-// ═══════════════════════════════════════════════════════════════════════════
-
--- Exact match
-SELECT Id, Name FROM Account
-WHERE Name = 'Acme Corporation'
-
--- Case-insensitive exact match (default behavior)
-SELECT Id, Name FROM Account
-WHERE Name = 'acme corporation'
-
--- Starts with pattern
-SELECT Id, Name FROM Account
-WHERE Name LIKE 'Acme%'
-
--- Contains pattern
-SELECT Id, Name FROM Account
-WHERE Name LIKE '%Corp%'
-
--- Ends with pattern (NOT indexed - use sparingly)
-SELECT Id, Name FROM Account
-WHERE Name LIKE '%Inc.'
-
--- Multiple values
-SELECT Id, Name, Industry FROM Account
-WHERE Industry IN ('Technology', 'Finance', 'Healthcare')
-
--- Exclude values
-SELECT Id, Name, Industry FROM Account
-WHERE Industry NOT IN ('Other', 'Unknown')
-
-// ═══════════════════════════════════════════════════════════════════════════
-// NUMERIC FILTERING
-// ═══════════════════════════════════════════════════════════════════════════
-
--- Greater than
-SELECT Id, Name, AnnualRevenue FROM Account
-WHERE AnnualRevenue > 1000000
-
--- Range
-SELECT Id, Name, Amount FROM Opportunity
-WHERE Amount >= 10000 AND Amount <= 100000
-
--- Not equal
-SELECT Id, Name, Amount FROM Opportunity
-WHERE Amount != 0
-
-// ═══════════════════════════════════════════════════════════════════════════
-// NULL HANDLING
-// ═══════════════════════════════════════════════════════════════════════════
-
--- Find records with null value
-SELECT Id, Name FROM Contact
-WHERE Email = null
-
--- Find records with non-null value
-SELECT Id, Name, Email FROM Contact
-WHERE Email != null
-
--- Find accounts without opportunities (using NOT IN)
-SELECT Id, Name FROM Account
-WHERE Id NOT IN (SELECT AccountId FROM Opportunity)
-
-// ═══════════════════════════════════════════════════════════════════════════
-// SORTING
-// ═══════════════════════════════════════════════════════════════════════════
-
--- Sort ascending (default)
-SELECT Id, Name FROM Account
-ORDER BY Name ASC
-
--- Sort descending
-SELECT Id, Name, AnnualRevenue FROM Account
-ORDER BY AnnualRevenue DESC
-
--- Multiple sort fields
-SELECT Id, Name, Industry, AnnualRevenue FROM Account
-ORDER BY Industry ASC, AnnualRevenue DESC
-
--- Nulls last
-SELECT Id, Name, AnnualRevenue FROM Account
-ORDER BY AnnualRevenue DESC NULLS LAST
-
-// ═══════════════════════════════════════════════════════════════════════════
-// PAGINATION
-// ═══════════════════════════════════════════════════════════════════════════
-
--- First page (records 1-100)
-SELECT Id, Name FROM Account
-ORDER BY Name
-LIMIT 100
-
--- Second page (records 101-200)
-SELECT Id, Name FROM Account
-ORDER BY Name
-LIMIT 100
-OFFSET 100
-
--- Note: OFFSET max is 2000. For larger datasets, use query locator in Apex.
-
-// ═══════════════════════════════════════════════════════════════════════════
-// COMBINED PATTERNS
-// ═══════════════════════════════════════════════════════════════════════════
-
--- Active technology accounts with high revenue created this year
-SELECT Id, Name, Industry, AnnualRevenue, CreatedDate
-FROM Account
-WHERE Industry = 'Technology'
-AND AnnualRevenue > 500000
-AND IsActive__c = true
-AND CreatedDate = THIS_YEAR
-ORDER BY AnnualRevenue DESC
-LIMIT 50
-
--- Contacts with Gmail addresses at accounts in California
-SELECT Id, FirstName, LastName, Email, Account.Name
-FROM Contact
-WHERE Email LIKE '%@gmail.com'
-AND Account.BillingState = 'CA'
-ORDER BY LastName
-
--- Open cases older than 7 days
-SELECT Id, CaseNumber, Subject, Status, CreatedDate, Owner.Name
-FROM Case
-WHERE IsClosed = false
-AND CreatedDate < LAST_N_DAYS:7
-ORDER BY CreatedDate ASC