@salesforce/afv-skills 1.16.0 → 1.18.0

package/skills/running-code-analyzer/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: running-code-analyzer
-description: "Run Salesforce Code Analyzer to scan code for security, performance, best practice, and code style violations. Supports all engines (PMD, ESLint, CPD, RetireJS, Flow, SFGE, ApexGuru), targets (files, folders, git diff), categories, and severities. TRIGGER when: user says 'scan my code', 'check for security issues', 'run PMD/ESLint', 'find duplicates', 'analyze Flows', 'check vulnerable libraries', 'AppExchange review', 'lint my LWC', 'static analysis', 'code quality', or mentions engines/file types (.cls, .trigger, .js, .flow-meta.xml). DO NOT TRIGGER when: user wants to fix code without scanning, or asks about installation/configuration."
+description: "Run Salesforce Code Analyzer to scan code for security, performance, best practice, and code style violations. Supports all engines (PMD, ESLint, CPD, RetireJS, Flow, SFGE, ApexGuru), targets (files, folders, git diff), categories, and severities. Also handles post-scan exploration: filtering results by engine/severity/category/file, and explaining what specific rules mean. TRIGGER when: user says 'scan my code', 'check for security issues', 'run PMD/ESLint', 'find duplicates', 'analyze Flows', 'check vulnerable libraries', 'AppExchange review', 'lint my LWC', 'static analysis', 'code quality', 'show only security violations', 'what is this rule', 'explain ApexCRUDViolation', 'filter results', or mentions engines/file types (.cls, .trigger, .js, .flow-meta.xml). Use this skill for scanning, exploring results, understanding rules, and listing available rules. DO NOT TRIGGER when: user wants to fix code without scanning, or asks ONLY about installation/configuration."
 allowed-tools: Read, Bash(sf code-analyzer), Bash(node), Bash(git diff), Bash(date), Write, Edit
 metadata:
   version: "1.0"
@@ -9,284 +9,233 @@ metadata:
 
 # Running Code Analyzer Skill
 
-## ⚠️ CRITICAL: Tool Selection
+## ⚠️ CRITICAL: Mandatory Script Usage
 
-**BEFORE DOING ANYTHING ELSE:**
+Every interaction with Code Analyzer results MUST go through the bundled scripts in `<skill_dir>/scripts/`. No exceptions.
 
-This skill MUST use the **Bash tool** to execute `sf code-analyzer run` and Node.js scripts.
+### ❌ WRONG — never do this:
 
-**DO NOT use these tools under any circumstances:**
-- ❌ `run_code_analyzer` (MCP tool)
-- ❌ `mcp__*` (any MCP tool)
-- ❌ Any tool containing `mcp` in its name
+```bash
+# WRONG: inline Python to parse results
+python3 -c "import json; data = json.load(open('results.json'))..."
 
-If you see a `run_code_analyzer` tool available, **ignore it completely**. Use only the Bash tool with `sf code-analyzer run`.
+# WRONG: inline Node.js to parse results
+node -e "const data = require('./results.json')..."
 
----
+# WRONG: jq to filter results
+cat results.json | jq '.violations[] | select(.engine=="pmd")'
 
-## Overview
-
-This skill translates natural language requests ("scan for security issues", "check my changes") into the correct `sf code-analyzer run` command, executes scans with any combination of engines/targets/severities, and presents actionable results. When engine-provided fixes are available, it discovers them, asks for user confirmation, applies them safely, and offers verification. Use this skill for static analysis, security reviews, AppExchange certification, code quality checks, or finding duplicates/vulnerabilities in Salesforce projects.
+# WRONG: reading the results file directly (it can be 10MB+)
+Read tool → code-analyzer-results-*.json
+```
 
----
+Also forbidden: `run_code_analyzer` and any `mcp__*` tool — Bash only.
 
-## Scope
+### ✅ RIGHT — always do this:
 
-**In scope:**
-- Running `sf code-analyzer run` with any combination of engines, targets, categories, severities
-- Parsing and presenting scan results in actionable format
-- Applying engine-provided auto-fixes when available
-- Handling diff-based scans (scan only changed files)
-- Supporting all output formats (JSON, HTML, SARIF, CSV, XML)
-- Troubleshooting scan failures and prerequisite issues
+```bash
+# Summarize scan results
+node "<skill_dir>/scripts/parse-results.js" "./code-analyzer-results-TIMESTAMP.json"
 
-**Out of scope:**
-- Installing or configuring Salesforce CLI or Code Analyzer plugin (use setup documentation)
-- Writing custom Code Analyzer rules or engines (separate skill needed)
-- AI-generated code fixes beyond engine-provided deterministic fixes
-- Deep code refactoring or architectural changes based on violations
-- Setting up CI/CD integration for automated scanning (separate workflow skill)
+# Filter/rank/query results (by engine, severity, file, rule, category)
+node "<skill_dir>/scripts/query-results.js" "./code-analyzer-results-TIMESTAMP.json" --engine pmd --summary
 
----
+# List/browse available rules (by engine, category, language, severity)
+node "<skill_dir>/scripts/list-rules.js" "Security" --top 10
 
-## Command Syntax Rules (READ THIS FIRST)
+# Look up what a rule means
+node "<skill_dir>/scripts/describe-rule.js" "ApexCRUDViolation" --engine pmd
 
-**The following rules are ABSOLUTE and override any prior knowledge:**
+# Discover fixable violations
+node "<skill_dir>/scripts/discover-fixes.js" "./code-analyzer-results-TIMESTAMP.json"
 
-1. **The command is `sf code-analyzer run`** — NOT `sf scanner run` (deprecated v3 command)
-2. **There is NO `--format` flag** — use `--output-file <path>.<ext>` instead (extension determines format)
-3. **ALWAYS use `--output-file`** to write results to a file — do NOT rely on terminal stdout
-4. **ALWAYS include `--output-file`** with a timestamped filename (e.g., `./code-analyzer-results-20260512-143022.json`)
-5. **Do NOT run in background** — use foreground with timeout of 1200000ms for large scans
-6. **INVALID v3 flags:** `--format`, `--engine`, `--category`, `--json` — these cause errors, use `--rule-selector` and `--output-file` instead
-7. **NEVER use MCP tools** — ONLY use the Bash tool to execute `sf code-analyzer run`
-8. **Tool restriction:** This skill MUST use ONLY: Read, Bash, Write, Edit tools
-9. **Forbidden tools:** Do NOT use any MCP tools (mcp__*), Agent tool, or web tools
-10. **Script execution:** ALL scripts MUST be executed via `node <skill_dir>/scripts/*.js` using the Bash tool
+# Apply fixes (after user confirms)
+node "<skill_dir>/scripts/apply-fixes.js" "./code-analyzer-results-TIMESTAMP.json"
 
-**Why:** The v4+ CLI redesigned the flag interface. Old v3 flags cause "unknown flag" errors.
+# Summarize applied fixes
+node "<skill_dir>/scripts/summarize-fixes.js" "./code-analyzer-results-TIMESTAMP.json"
 
-**For complete flag reference and rule selector syntax**, see `<skill_dir>/references/flag-reference.md`.
+# Filter vendor files (jQuery, Bootstrap, *.min.js) before applying fixes
+node "<skill_dir>/scripts/filter-violations.js" "./code-analyzer-results-TIMESTAMP.json" "./code-analyzer-results-TIMESTAMP-filtered.json" --report
+```
 
----
+`<skill_dir>` is the absolute path to the directory containing this SKILL.md. **Never** use `./scripts/` — that resolves against the user's CWD, not the skill dir.
 
-## Prerequisites
+Any aggregation, filter, or rank question ("which file has the most violations?", "how many PMD issues?", "top rules by count", "break down by severity") is answered by `query-results.js` — its output already includes `topRules`, `topFiles`, and `severityCounts`.
 
-User must have: **Salesforce CLI** (`sf`), **@salesforce/plugin-code-analyzer** (v5.x+), **Java 11+** (PMD/CPD/SFGE), **Node.js 18+** (ESLint/RetireJS), **Python 3** (Flow), **authenticated org** (ApexGuru).
+---
 
-If a scan fails, read `<skill_dir>/references/error-handling.md`. For quick command examples, see `<skill_dir>/references/quick-start.md`.
+## Overview
 
----
+This skill translates natural-language requests ("scan for security issues", "check my changes") into the correct `sf code-analyzer run` command, executes scans across any combination of engines/targets/severities, and presents actionable results. When engine-provided fixes are available, it discovers them, asks for user confirmation, applies them safely, and offers verification. Use it for static analysis, security reviews, AppExchange certification, code-quality checks, and finding duplicates/vulnerabilities in Salesforce projects.
 
-## Tool Usage Rules
+**In scope:** running scans, parsing/filtering/ranking results, applying engine auto-fixes, diff-based scans, all output formats (JSON/HTML/SARIF/CSV/XML), describing/listing rules, scan-failure troubleshooting.
 
-**Allowed:** Bash (sf code-analyzer, node, git, date), Read, Write, Edit  
-**Forbidden:** MCP tools, Agent tool, Web tools, other skills
+**Out of scope:** installing/configuring `sf` or the plugin (→ `configuring-code-analyzer`), writing custom rules/engines, AI-generated fixes beyond engine-provided ones, deep refactoring, CI/CD setup (→ `configuring-code-analyzer`).
 
-This skill owns the complete scan-fix-verify workflow. Using MCP tools bypasses the validated script workflow.
+**Allowed tools:** Bash (`sf code-analyzer`, `node`, `git diff`, `date`), Read, Write, Edit. **Forbidden:** any MCP tool, Agent tool, web tools, other skills, Python, `jq`, inline scripts/heredocs. This skill owns the complete scan-fix-verify-query-explain workflow end-to-end.
 
 ---
 
-## Quick Start: Common Patterns
+## Command Syntax Rules (READ FIRST — ABSOLUTE)
 
-Use this decision tree for fast pattern matching before going to Step 1 detailed parsing:
+1. The command is **`sf code-analyzer run`** — NOT `sf scanner run` (deprecated v3).
+2. **No `--format` flag.** Use `--output-file <path>.<ext>`; the extension determines the format.
+3. **Always** pass `--output-file` with a timestamped name (e.g., `./code-analyzer-results-20260512-143022.json`) — do not rely on stdout.
+4. **Foreground only** (no `run_in_background`); timeout 1200000ms for large scans.
+5. **Invalid v3 flags** that cause errors: `--format`, `--engine`, `--category`, `--json`. Use `--rule-selector` + `--output-file` instead.
+6. **Tool restriction:** Bash, Read, Write, Edit only. No MCP tools, no Agent tool, no web tools, no other skills.
 
-| User Says | Action | Rule Selector | Notes |
-|-----------|--------|---------------|-------|
-| "scan my code" / "run code analyzer" | Default scan | `Recommended` | Curated rule set, all file types |
-| "check for security issues" / "security review" | Security scan | `all:Security:(1,2)` | All engines, Critical+High only |
-| "scan my changes" / "check the diff" | Diff-based scan | Get changed files via `git diff`, filter to scannable types, use `--target` | See Step 1.5 for filtering logic |
-| "run PMD" / "check my Apex" | PMD only | `pmd` | Apex classes and triggers |
-| "lint my LWC" / "check my JavaScript" | ESLint only | `eslint` | JavaScript/TypeScript/LWC |
-| "find duplicates" / "check for copy-paste" | CPD (Copy-Paste Detector) | `cpd` | Detects code clones |
-| "check for vulnerabilities" / "scan libraries" | RetireJS | `retire-js` | JavaScript library CVEs |
-| "deep analysis" / "data flow analysis" | SFGE (Graph Engine) | `sfge` | Requires Java 11+, 10-20min, use `--workspace "force-app"` |
-| "performance analysis" / "governor limits" | ApexGuru | `apexguru` | Requires authenticated org |
-| "analyze my Flows" | Flow engine | `flow` | Target: `**/*.flow-meta.xml`, requires Python 3 |
-| "AppExchange security review" | AppExchange scan | `all:Security:(1,2)` | Read `<skill_dir>/references/special-behaviors.md` → AppExchange section |
+Why: the v4+ CLI redesigned the flag interface; v3 flags now error.
 
-**If the pattern matches above**, proceed directly to Step 3 (Build Command). Otherwise, continue to Step 1 for detailed parsing.
+Full flag/selector docs: `<skill_dir>/references/flag-reference.md`.
 
 ---
 
-## Step 1: Parse the User's Intent
-
-Analyze the user's request along these 7 dimensions. Any can be combined freely:
-
-### 1.1 ENGINE — Which analysis engine(s)?
+## Prerequisites
 
-Map user keywords to `--rule-selector` values:
-- PMD / Apex rules → `pmd`
-- ESLint / JS/TS rules / lint → `eslint`
-- Flows / Flow analysis → `flow`
-- duplicates / copy-paste / CPD → `cpd`
-- vulnerabilities / CVE / libraries / RetireJS → `retire-js`
-- SFGE / data flow / deep analysis → `sfge`
-- performance / ApexGuru → `apexguru`
-- regex / pattern rules → `regex`
-- all engines / everything → `all`
-- Not specified / general "scan" → `Recommended` (default)
+User needs: **Salesforce CLI** (`sf`), **@salesforce/plugin-code-analyzer** (v5.x+), **Java 11+** (PMD/CPD/SFGE), **Node.js 18+** (ESLint/RetireJS), **Python 3** (Flow), **authenticated org** (ApexGuru).
 
-### 1.2 CATEGORY — What kind of issues?
+Pre-flight: run `sf code-analyzer --help 2>&1 | head -1`. If that fails, or if a scan reports an engine startup error (e.g., "PMD failed to start", "java: command not found", "SFGE failed"):
 
-Map user keywords to category tags:
-- security / vulnerabilities / OWASP → `Security`
-- performance / speed / optimization → `Performance`
-- best practices / quality → `BestPractices`
-- code style / formatting → `CodeStyle`
-- design / complexity → `Design`
-- error prone / bugs → `ErrorProne`
-- documentation / comments → `Documentation`
+1. **Stop** — do not attempt to install/diagnose prerequisites yourself.
+2. **Delegate to `configuring-code-analyzer`** — it handles all setup.
+3. After it finishes, return here and re-run the scan.
 
-### 1.3 SEVERITY — How critical?
+If a scan fails for other reasons, see `<skill_dir>/references/error-handling.md`.
 
-**Severity levels:** 1=Critical (must fix), 2=High (should fix), 3=Moderate (recommended), 4=Low (nice to fix), 5=Info (FYI)
+---
 
-Map user keywords:
-- "critical only" / "sev 1" → `1`
-- "critical and high" / "sev 1-2" → `(1,2)`
-- "moderate and above" / "sev 1-3" → `(1,2,3)`
+## Quick Start: Common Patterns
 
-### 1.4 SPECIFIC RULE — Named rule?
+Match the request below; if it matches, jump to Step 3 (Build Command). Otherwise, walk Step 1.
+
+| User Says | Rule Selector | Notes |
+|-----------|---------------|-------|
+| "scan my code" / "run code analyzer" | `Recommended` | Curated set, all file types |
+| "check for security issues" / "security review" | `all:Security:(1,2)` | All engines, Critical+High |
+| "scan my changes" / "check the diff" | (see Step 1.5) | Get files via `git diff`, filter to scannable types, pass via `--target` |
+| "run PMD" / "check my Apex" | `pmd` | Apex classes and triggers |
+| "lint my LWC" / "check my JavaScript" | `eslint` | JavaScript/TypeScript/LWC |
+| "find duplicates" / "check for copy-paste" | `cpd` | Code clones |
+| "check for vulnerabilities" / "scan libraries" | `retire-js` | JavaScript library CVEs |
+| "deep analysis" / "data flow analysis" | `sfge` | Java 11+, 10–20 min, use `--workspace "force-app"` |
+| "performance analysis" / "governor limits" | `apexguru` | Authenticated org required |
+| "analyze my Flows" | `flow` | `--target **/*.flow-meta.xml`, Python 3 |
+| "AppExchange security review" | `all:Security:(1,2)` | See `<skill_dir>/references/special-behaviors.md` → AppExchange |
 
-If the user mentions a specific rule by name (e.g., "ApexCRUDViolation", "no-unused-vars"):
-- Map to: `--rule-selector <engine>:<ruleName>`
-- If engine is ambiguous, use just the rule name: `--rule-selector <ruleName>`
+---
 
-**⚠️ IMPORTANT — Partial Rule Names:** The `--rule-selector` flag requires the EXACT full rule name (e.g., `@salesforce-ux/slds/no-hardcoded-values-slds2`, not `no-hardcoded-values`). It does NOT support wildcards or partial matches.
+## Step 1: Parse the User's Intent
 
-**When you are NOT 100% certain of the full rule name:**
-- **Do NOT guess** — a wrong name returns 0 results and wastes a scan cycle
-- Instead, **look up the rule first** using the `sf code-analyzer rules` command with grep:
-  ```bash
-  sf code-analyzer rules --rule-selector all 2>&1 | grep -i "USER_KEYWORD"
-  ```
-- Extract the full rule name from the output, then use it in your scan command
-- If grep returns multiple matches, present them to the user and ask which one they meant
-- If grep returns 0 matches, tell the user no rule matched their keyword
+Analyze the request along these 7 dimensions; any can combine.
 
-### 1.5 TARGET — What files to scan?
+### 1.1 ENGINE
+PMD/Apex → `pmd` · ESLint/JS/TS/lint → `eslint` · Flows → `flow` · duplicates/CPD → `cpd` · vulnerabilities/CVE/RetireJS → `retire-js` · SFGE/data flow → `sfge` · performance/ApexGuru → `apexguru` · regex → `regex` · everything → `all` · unspecified → `Recommended`.
 
-Map user keywords:
-- Specific file/folder → `--target <path>`
-- Glob pattern / "all Apex classes" → `--target **/*.cls,**/*.trigger`
-- "my changes" / "diff" → Run `git diff --name-only [base]...HEAD`, filter to scannable types, pass as `--target`
-- "LWC" → `--target **/lwc/**`
-- "Flows" → `--target **/*.flow-meta.xml`
-- Not specified → Entire workspace (omit `--target`)
+### 1.2 CATEGORY
+security/OWASP → `Security` · performance → `Performance` · best practices → `BestPractices` · style/format → `CodeStyle` · design/complexity → `Design` · bugs → `ErrorProne` · docs → `Documentation`.
 
-**For diff filtering details:** See `<skill_dir>/references/special-behaviors.md`.
+### 1.3 SEVERITY
+1=Critical · 2=High · 3=Moderate · 4=Low · 5=Info. "critical only" → `1` · "critical+high" → `(1,2)` · "moderate and above" → `(1,2,3)`.
 
-### 1.6 OUTPUT — What format?
+### 1.4 SPECIFIC RULE
+If the user names a rule (e.g., "ApexCRUDViolation", "no-unused-vars"): `--rule-selector <engine>:<ruleName>`, or just `<ruleName>` if engine is ambiguous.
 
-**DEFAULT:** Always JSON. Only change if user EXPLICITLY requests another format.
+⚠️ **Partial names:** `--rule-selector` requires the **exact full** rule name (e.g., `@salesforce-ux/slds/no-hardcoded-values-slds2`, not `no-hardcoded-values`). No wildcards. If you are not 100% certain, look it up first — **do not guess**:
+```bash
+sf code-analyzer rules --rule-selector all 2>&1 | grep -i "USER_KEYWORD"
+```
+Multiple matches → ask the user which. Zero matches → tell the user nothing matched.
 
-**Naming:** `./code-analyzer-results-<YYYYMMDD-HHmmss>.<ext>` (timestamp via `TIMESTAMP=$(date +%Y%m%d-%H%M%S)`)
+### 1.5 TARGET
+specific path → `--target <path>` · glob ("all Apex") → `--target **/*.cls,**/*.trigger` · "my changes"/"diff" → `git diff --name-only [base]...HEAD`, filter to scannable types, pass as `--target` · "LWC" → `--target **/lwc/**` · "Flows" → `--target **/*.flow-meta.xml` · unspecified → omit (entire workspace).
 
-Formats: `.json` (default), `.html` (report), `.sarif` (GitHub/IDE), `.csv` (spreadsheet), `.xml`
+Diff-filtering details: `<skill_dir>/references/special-behaviors.md`.
 
-### 1.7 COMPARISON — Delta/trend analysis?
+### 1.6 OUTPUT
+**Default JSON.** Only change if the user explicitly asks. Name: `./code-analyzer-results-<YYYYMMDD-HHmmss>.<ext>` via `TIMESTAMP=$(date +%Y%m%d-%H%M%S)`. Formats: `.json` (default), `.html`, `.sarif`, `.csv`, `.xml`.
 
-Map user keywords:
-- "new since main" → `git diff --name-only main...HEAD` → scan those files
-- "new since last commit" → `git diff --name-only HEAD~1`
-- "compared to develop" → `git diff --name-only develop...HEAD`
+### 1.7 COMPARISON / DELTA
+"new since main" → `git diff --name-only main...HEAD` → scan those · "since last commit" → `HEAD~1` · "vs develop" → `develop...HEAD`.
 
 ---
 
 ## Step 2: Build the Rule Selector
 
-**Syntax:** `:` = AND, `,` = OR, `()` = grouping
+Syntax: `:` = AND, `,` = OR, `()` = grouping.
 
-**Examples:**
 - Engine only: `pmd`
 - Engine + category: `pmd:Security`
 - Engine + severity: `pmd:2`
-- Complex: `(pmd,eslint):Security:(1,2)` = (PMD or ESLint) AND Security AND (sev 1 or 2)
+- Complex: `(pmd,eslint):Security:(1,2)` = (PMD or ESLint) AND Security AND sev (1 or 2)
 - Specific rule: `pmd:ApexCRUDViolation`
-- All rules: `all`
+- All: `all`
 
-**More examples:** `<skill_dir>/references/command-examples.md`
+More: `<skill_dir>/references/command-examples.md`.
 
 ---
 
 ## Step 3: Build the Full Command
 
-Generate timestamp: `TIMESTAMP=$(date +%Y%m%d-%H%M%S)`
-
-Build command:
 ```bash
+TIMESTAMP=$(date +%Y%m%d-%H%M%S)
 sf code-analyzer run \
   --rule-selector <selector> \
-  --target <targets> \              # optional
-  --output-file "./code-analyzer-results-${TIMESTAMP}.json" \  # DEFAULT: JSON
-  --include-fixes \                 # always
-  --workspace <path>                # optional
+  --target <targets> \                                              # optional
+  --output-file "./code-analyzer-results-${TIMESTAMP}.json" \       # default JSON
+  --include-fixes \                                                 # always
+  --workspace <path>                                                # optional
 ```
 
-**Key decisions:**
-- DEFAULT: timestamped JSON (`.json`). Only change format if user explicitly requests HTML/SARIF/CSV/XML.
-- Always include `--include-fixes` (enables Step 6 auto-fix)
-- Omit `--target` to scan entire workspace
-- For diff-based scans: get files via `git diff --name-only`, filter to scannable types, pass as `--target`
+- Default to timestamped JSON; only change format on explicit request.
+- Always pass `--include-fixes` (enables Step 6 auto-fix).
+- Omit `--target` to scan the whole workspace.
+- Diff scans: `git diff --name-only` → filter scannable types → pass as `--target`.
 
-**Special cases:** See `<skill_dir>/references/special-behaviors.md` for SFGE/ApexGuru/AppExchange/diff filtering.
+Special cases (SFGE/ApexGuru/AppExchange/diff): `<skill_dir>/references/special-behaviors.md`.
 
 ---
 
 ## Step 4: Execute the Scan
 
-**⚠️ TOOL REQUIREMENT: Use Bash tool ONLY. DO NOT use run_code_analyzer (MCP tool) or any MCP tool.**
+Use the **Bash tool only** — never the `run_code_analyzer` MCP tool.
 
-**Rules:** Foreground only (no `run_in_background`), hardcoded filename (not `$TIMESTAMP`), timeout 1200000ms, no `sleep`, log output to timestamped file.
-
-**Steps:**
-
-1. Generate timestamp: `date +%Y%m%d-%H%M%S` → capture output (e.g., `20260512-143022`) **using Bash tool**
-2. Tell user:
+1. Generate the timestamp via Bash: `date +%Y%m%d-%H%M%S` → e.g. `20260512-143022`.
+2. Tell the user:
    ```
    Starting scan...
    Results: ./code-analyzer-results-20260512-143022.json
    Log:     ./code-analyzer-results-20260512-143022.log
    May take several minutes for large codebases.
    ```
-3. Run command with literal timestamp in filename and `tee` to capture log (timeout: 1200000):
-   
-   ⚠️ **IMPORTANT:** Use the Bash tool, NOT the run_code_analyzer MCP tool.
-   
+3. Run with the **literal** timestamp baked in (not `$TIMESTAMP`), foreground, timeout 1200000ms, `tee` to a `.log`:
    ```bash
-   sf code-analyzer run --rule-selector Recommended --output-file "./code-analyzer-results-20260512-143022.json" --include-fixes 2>&1 | tee "./code-analyzer-results-20260512-143022.log"
+   sf code-analyzer run --rule-selector Recommended \
+     --output-file "./code-analyzer-results-20260512-143022.json" \
+     --include-fixes 2>&1 | tee "./code-analyzer-results-20260512-143022.log"
    ```
-4. After completion: Exit 0 = success. Error output → check both the log file and `<skill_dir>/references/error-handling.md`.
-5. IMMEDIATELY parse results (Step 5). Do NOT ask user what they want.
+4. Exit 0 = success. On error, read both the log file and `<skill_dir>/references/error-handling.md`.
+5. **Immediately** parse results (Step 5) — do not ask the user what to do next.
 
 ---
 
 ## Step 5: Parse and Present Results
 
-### Parsing Rules:
-
-1. **Execute the parse script using `<skill_dir>`** — see below
-2. **NEVER use `jq` to parse results** — jq one-liners WILL fail due to shell quoting issues
-3. **Run it IMMEDIATELY after the scan** — do NOT ask the user "what would you like next?"
-
-### Script Execution
-
-All scripts are bundled in the `scripts/` subdirectory of the same directory that contains this SKILL.md file. Use the absolute path to that directory — do NOT use `./scripts/` as that resolves relative to the current working directory, not the skill directory.
+Run the parse script straight after the scan — do not pause to ask:
 
 ```bash
-node <skill_dir>/scripts/parse-results.js "./code-analyzer-results-TIMESTAMP.json"
+node "<skill_dir>/scripts/parse-results.js" "./code-analyzer-results-TIMESTAMP.json"
 ```
 
 ⚠️ **DO NOT:**
 - ❌ Invent or generate script code yourself
 - ❌ Use bare relative paths like `node scripts/parse-results.js` (won't resolve from user's CWD)
 - ❌ Use heredocs or inline script content
-- ❌ Use `jq` as a substitute for the parse script
+- ❌ Use `jq` as a substitute for the parse script (shell quoting will break)
+- ❌ Read the JSON file directly
 
-### How to Present Results:
-
-**ALWAYS present a concise summary, then point to the output file for full details.**
+### Presentation template
 
 ```
 ## Scan Complete
@@ -305,44 +254,30 @@ node <skill_dir>/scripts/parse-results.js "./code-analyzer-results-TIMESTAMP.jso
 | # | Rule | Engine | Sev | File | Line |
 |---|------|--------|-----|------|------|
 | 1 | ApexCRUDViolation | pmd | 2 | AccountService.cls | 42 |
-| 2 | ApexSOQLInjection | pmd | 1 | QueryHelper.cls | 18 |
-| ... (show up to 10 most critical) |
+| ... up to 10 most critical |
 
 ### Top Rules by Frequency
 | Rule | Engine | Count |
 |------|--------|-------|
 | no-var | eslint | 170 |
-| ApexDoc | pmd | 165 |
 | ... |
 
 Full results: `./code-analyzer-results-20260512-143022.json`
 ```
 
-### Result Presentation Rules:
-
-- **0 violations**: "Scan complete — no violations found! Output: `<path>`"
-- **1-10**: Show all violations in table
-- **11-50**: Show severity counts + top 10 violations
-- **50-5000**: Show counts + top 10 violations + top 10 rules + top 5 files
-- **5000+**: Same as 50-5000, plus suggest narrowing scope (severity/category/folder)
+Scale to result size: **0** → "no violations found"; **1–10** → all in one table; **11–50** → severity counts + top 10; **50–5000** → counts + top 10 violations + top 10 rules + top 5 files; **5000+** → same, plus suggest narrowing scope (severity/category/folder). Always end with the output path and offer next actions: filter / explain rule / apply fixes.
 
-**Always end with:** Output file path + next-action offers (explain rules / apply fixes)
-
-**For large result sets:** See `<skill_dir>/references/special-behaviors.md`.
+Large-result handling: `<skill_dir>/references/special-behaviors.md`.
 
 ---
 
 ## Step 6: Apply Engine-Provided Fixes (Post-Scan)
 
-After presenting results, check if violations have **engine-provided fixes** (deterministic, not AI-generated).
-
-**Rules:** NEVER apply without confirmation. Use EXACT scripts from `<skill_dir>/scripts/`. Filter vendor files if needed, then: Discover → Apply → Summarize.
+Engine-provided fixes are **deterministic** (not AI-generated). Flow: vendor filter (if needed) → discover → present → **wait for user confirmation** → apply → summarize.
 
-**Flow:** Filter vendor (6.1 if needed) → discover (6.2) → present (6.3) → ASK user → apply (6.4) → summarize (6.5) → present results.
+### 6.1 Vendor file filter (when needed)
 
-### 6.1 — Check for vendor files (if needed)
-
-If user said "fix my code" or "project source", or if top files by violation count are vendor libraries (jQuery, Bootstrap, *.min.js), run:
+Run if the user said "fix my code" / "project source", or if top-violation files are vendor libs (jQuery, Bootstrap, `*.min.js`):
 
 ```bash
 node "<skill_dir>/scripts/filter-violations.js" \
@@ -351,31 +286,23 @@ node "<skill_dir>/scripts/filter-violations.js" \
   --report
 ```
 
-Present: "Excluded X vendor files (Y violations) - jQuery, Bootstrap, etc. Applying fixes to Z project files only."
-
-Use filtered file for Step 6.3+. **See:** `<skill_dir>/references/vendor-file-handling.md` for detailed logic.
+Report: "Excluded X vendor files (Y violations) — jQuery, Bootstrap, etc. Applying fixes to Z project files only." Use the filtered file in 6.2+. Detection logic: `<skill_dir>/references/vendor-file-handling.md`.
 
-### 6.2 — Discover fixable violations
+### 6.2 Discover
 
 ```bash
 node "<skill_dir>/scripts/discover-fixes.js" "./code-analyzer-results-TIMESTAMP.json"
 ```
 
-(Use filtered file from Step 6.1 if created.)
-
-### 6.3 — Present fixable violations and ASK for confirmation
-
-After running the discovery script, present results:
+### 6.3 Present + ASK (then STOP)
 
 ```
 ### Engine-Provided Fixes Available
-
 **X of Y violations** have auto-fixes provided by the analysis engine:
 
 | Rule | Engine | Sev | Fixable Count |
 |------|--------|-----|---------------|
 | no-var | eslint | 3 | 170 |
-| no-hardcoded-values-slds2 | eslint | 4 | 76 |
 | ... |
 
 These are safe, deterministic fixes generated by the engines (not AI-generated).
@@ -383,39 +310,30 @@ These are safe, deterministic fixes generated by the engines (not AI-generated).
 Would you like me to apply these fixes? (yes / no / select specific rules)
 ```
 
-### ⚠️ STOP HERE AND WAIT FOR USER RESPONSE.
+⚠️ **Stop and wait for the user's reply, even if they originally said "scan and fix everything".** Apply only on a fresh "yes" / "apply" / "go ahead" in the next turn.
 
-**Even if the user originally said "scan and fix everything", you MUST still stop here and wait.** Present the table, ask the question, and WAIT for a response in the NEXT turn.
-
-### 6.4 — Apply fixes ONLY after user confirms
-
-**Only proceed after user says "yes", "apply", "go ahead" IN A SEPARATE RESPONSE.**
+### 6.4 Apply
 
 ```bash
 node "<skill_dir>/scripts/apply-fixes.js" "./code-analyzer-results-TIMESTAMP.json"
 ```
+(Filtered file if 6.1 created one.)
 
-(Use filtered file if Step 6.1 created one.)
-
-### 6.5 — After applying, ALWAYS run the summary script
-
-⚠️ **MANDATORY**: After the apply script completes, you MUST run the summary script as your VERY NEXT action.
+### 6.5 Summarize (MANDATORY immediately after 6.4)
 
 ```bash
 node "<skill_dir>/scripts/summarize-fixes.js" "./code-analyzer-results-TIMESTAMP.json"
 ```
 
-Then present to the user:
+Then present:
 
 ```
 ### Engine-Provided Fixes Applied Successfully ✓
-
 **Applied X auto-fixes across Y files.**
 
 | Severity | Fixes Applied |
 |----------|---------------|
 | Critical (1) | X |
-| High (2) | X |
 | ... |
 
 | Rule | Fixes Applied |
@@ -426,56 +344,130 @@ Then present to the user:
 Want me to re-run the scan to verify the fixes resolved the violations?
 ```
 
-### 6.6 — If user declines: Skip. If selects rules: filter. If "all": run as-is.
+### 6.6 — Handling the user's choice
+- **Decline / "no":** skip apply, skip summarize. Do not re-scan.
+- **"Select rules":** filter the discovery list to those rules and pass the filtered file to `apply-fixes.js`.
+- **"All" / "yes":** run `apply-fixes.js` against the full (or vendor-filtered) results file as-is.
+
+### 6.7 — Optional re-scan for verification
+If the user accepts the offer in 6.5, re-run the same scan with a **new timestamp** (do not overwrite the original). Compare violation counts before vs. after and show the delta — fixes that resolved cleanly will drop out; remaining violations either need manual remediation or are unrelated.
 
-### 6.7 — Re-scan (optional): Re-run with new timestamp, compare before/after counts.
 ---
-## Rules / Constraints
-
-| Constraint | Rationale |
-|-----------|-----------|
-| Timestamped output (JSON + log) | Prevents overwrite; enables history tracking |
-| Use `tee` for logs | Keeps logs in working dir with matching timestamp |
-| Never use `--format` flag | Removed in v4+; use `--output-file <path>.<ext>` instead |
-| Foreground scans, 1200000ms timeout | SFGE takes 10-20min; backgrounding loses output |
-| Execute scripts from `<skill_dir>/scripts/` | Never write inline scripts or heredocs |
-| Never apply fixes without confirmation | User must explicitly approve code modifications |
-| Check for vendor files before fixes | If 50%+ vendor (jQuery, Bootstrap), filter first |
-| Run fix scripts in order | Filter (if needed) → Discover → Apply → Summarize |
-| SFGE needs explicit `--workspace` | Prevents template file compilation errors |
-| Look up partial rule names first | Guessing fails; use `sf code-analyzer rules` to find exact name |
-| ONLY Bash tool, never MCP | run_code_analyzer MCP tool bypasses script workflow |
-| Never invoke other skills for fixes | This skill owns complete workflow end-to-end |
+
+## Step 7: Query and Filter Existing Results
+
+After Step 5, the user may want to **drill into specific subsets** without re-running the entire scan. This step handles all result-exploration requests.
+
+### When to trigger
+Activate when the user asks to slice, filter, rank, or explore existing results:
+- "Show me just the security violations"
+- "What's in AccountService.cls?"
+- "Show only PMD issues" / "Filter to critical and high"
+- "What ESLint rules fired?" / "Show violations in the lwc folder"
+- "Top 20 most severe" / "Which file has the most violations?"
+- "What are the most common rules?" / "How many violations per engine?" / "Break it down by severity"
+
+**Important:** Any question about existing scan results — filtering, ranking, counting, aggregating — MUST use `query-results.js`. NEVER write inline Python, `jq`, or ad-hoc scripts to parse the results JSON. The query script already provides `topRules`, `topFiles`, and `severityCounts` in its output.
+
+### How to execute
+Run the query script against the **same results file** from Step 4 (no re-scan needed):
+
+```bash
+node "<skill_dir>/scripts/query-results.js" "./code-analyzer-results-TIMESTAMP.json" [options]
+```
+
+| User says | Options |
+|-----------|---------|
+| "security violations" | `--category Security` |
+| "PMD issues only" | `--engine pmd` |
+| "critical and high" / "sev 1-2" | `--severity 1,2` |
+| "in AccountService.cls" | `--file AccountService.cls` |
+| "the ApexCRUDViolation rule" | `--rule ApexCRUDViolation` |
+| "top 20" | `--top 20` |
+| "sort by file" | `--sort file` |
+| "just give me counts" | `--summary` |
+| "which file has the most violations?" | `--sort file --summary` (read `topFiles`) |
+| "which file has most PMD violations?" | `--engine pmd --summary` (read `topFiles`) |
+| "most common rules?" | `--summary` (read `topRules`) |
+| "how many per engine?" | use Step 5's summary, or run with `--engine X --summary` per engine |
+| Combinations | `--engine pmd --severity 1,2 --top 5` |
+
+Output format and presentation templates: `<skill_dir>/references/post-scan-workflows.md`.
 
 ---
 
-## Gotchas
+## Step 8: Describe a Rule
+
+When the user asks "what does this rule mean?" or "how do I fix this?", use this step to look up and explain a specific rule.
 
-| Issue | Why It Happens | Solution |
-|-------|---------------|----------|
-| `--format` flag error | Removed in v4+ | Use `--output-file <path>.<ext>` |
-| Scan returns 0 results | Invalid rule selector | Run `sf code-analyzer rules --rule-selector <selector>` to verify |
-| SFGE compilation error | Template files in workspace | Set `--workspace "force-app"` |
-| jq parsing fails | Shell quoting issues | Use `node "<skill_dir>/scripts/parse-results.js"` |
-| Inline scripts written | LLM generates custom code | NEVER write scripts — use existing from <skill_dir>/scripts/ |
-| Scan times out | Large SFGE | Increase timeout to 1200000ms |
-| run_code_analyzer MCP used | LLM prefers MCP over Bash | Use Bash tool ONLY |
-| Other skills invoked | LLM delegates to other skills | Use apply-fixes.js from this skill only |
-| Most violations are vendor | Includes jQuery, Bootstrap, *.min.js | Run filter-violations.js before applying fixes |
+### When to trigger
+- "What is ApexCRUDViolation?"
+- "Explain this rule" / "Why is this flagged?"
+- "What does no-var mean?"
+- "How do I fix OperationWithLimitsInLoop?"
+- "Tell me about this violation"
+
+### How to execute
+
+```bash
+node "<skill_dir>/scripts/describe-rule.js" "<rule-name>" [--engine <engine>]
+```
+
+Pass `--engine` when known (from scan context); omit for a broader search. Returns one of `success` / `multiple_matches` / `not_found`. Status handling and templates: `<skill_dir>/references/post-scan-workflows.md`.
 
 ---
 
-## Output Expectations
+## Step 9: List Available Rules
+
+Triggers: "what security rules are available?", "list all PMD rules", "rules for JavaScript", "Recommended rules", "how many ESLint rules?", "rules for Apex".
 
-Every scan produces: timestamped JSON file, concise summary (severity/top violations/rules/files), next-action offers. If fixes applied: summary by severity/rule, offer verification.
+```bash
+node "<skill_dir>/scripts/list-rules.js" "<selector>" [options]
+```
+
+| User says | Selector | Options |
+|-----------|----------|---------|
+| "security rules" | `Security` | |
+| "PMD rules" | `pmd` | |
+| "ESLint security rules" | `eslint:Security` | |
+| "JavaScript rules" | `JavaScript` | |
+| "Apex rules" | `Apex` | |
+| "Recommended rules" | `Recommended` | |
+| "high severity rules" | `(1,2)` | |
+| "just give me counts" | `Recommended` | `--count-only` |
+| "top 10 security rules" | `Security` | `--top 10` |
+
+Filters: `--engine`, `--severity`, `--top` (default 100), `--count-only`. The script pre-validates selector tokens (catches typos like `secruity`) before calling the CLI. Presentation: `<skill_dir>/references/post-scan-workflows.md`.
+
+---
+
+## Constraints & Gotchas
+
+| Item | Why / Fix |
+|------|-----------|
+| Use timestamped JSON + `.log` via `tee` | Prevents overwrite; matches log to results |
+| `--format` flag | Removed in v4+; use `--output-file <path>.<ext>` |
+| Foreground, 1200000ms timeout | SFGE can take 10–20 min; backgrounding loses output |
+| Run scripts with absolute `<skill_dir>` path | `./scripts/` resolves against the user's CWD, not the skill dir |
+| Never apply fixes without confirmation | User must approve code modifications |
+| Vendor file check before fixes | If 50%+ vendor (jQuery/Bootstrap/`*.min.js`), filter first |
+| Fix-script order: filter (if needed) → discover → apply → summarize | Skipping summary leaves the user without an outcome report |
+| SFGE needs explicit `--workspace` | Otherwise template files cause compilation errors |
+| Look up partial rule names first | Guessing returns 0 results; use `sf code-analyzer rules` |
+| `ONLY` Bash tool, never MCP | `run_code_analyzer` and other MCP tools bypass the script workflow |
+| Never invoke other skills for fixes | This skill owns the full workflow end-to-end |
+| Query existing results, don't re-scan | Step 7 filters existing JSON instantly |
+| Scan returns 0 results | Invalid rule selector — verify with `sf code-analyzer rules --rule-selector <selector>` |
+| `jq` parsing fails | Shell quoting — use `parse-results.js` / `query-results.js` instead |
+| Inline scripts written by LLM | Never write scripts — use existing ones in `<skill_dir>/scripts/` |
+| Ranking/aggregation answered by ad-hoc Python | Always use `query-results.js`; output already has `topFiles`/`topRules`/`severityCounts` |
 
 ---
 
 ## Reference File Index
 
-`<skill_dir>` is the absolute path to the directory containing this SKILL.md file.
+**Scripts** (always execute via `node` with the absolute `<skill_dir>/` prefix, never Read):
 
-### Scripts (Always execute, never read)
 | File | When to use |
 |------|-------------|
 | `<skill_dir>/scripts/parse-results.js` | Step 5 — extract summary from scan JSON |
@@ -483,16 +475,21 @@ Every scan produces: timestamped JSON file, concise summary (severity/top violat
 | `<skill_dir>/scripts/discover-fixes.js` | Step 6.2 — identify fixable violations |
 | `<skill_dir>/scripts/apply-fixes.js` | Step 6.4 — apply engine fixes after user confirms |
 | `<skill_dir>/scripts/summarize-fixes.js` | Step 6.5 — summarize applied changes |
+| `<skill_dir>/scripts/query-results.js` | Step 7 — filter/drill into existing results without re-scanning |
+| `<skill_dir>/scripts/describe-rule.js` | Step 8 — look up rule description and documentation |
+| `<skill_dir>/scripts/list-rules.js` | Step 9 — list/browse available rules by selector with validation |
+
+**References** (read on demand):
 
-### References (Read when needed)
 | File | When to read |
-|------|-------------|
-| `<skill_dir>/references/quick-start.md` | Command syntax templates |
-| `<skill_dir>/references/flag-reference.md` | Flag docs, rule selector syntax |
-| `<skill_dir>/references/error-handling.md` | Scan failure diagnosis |
-| `<skill_dir>/references/engine-reference.md` | Engine capabilities, file types, rule tags |
-| `<skill_dir>/references/command-examples.md` | Uncommon command scenarios |
-| `<skill_dir>/references/special-behaviors.md` | SFGE/ApexGuru/AppExchange/diff/large scans |
-| `<skill_dir>/references/vendor-file-handling.md` | Vendor file detection and filtering logic |
-
-Examples in `<skill_dir>/examples/` show output structure validation and command patterns (basic/large/security scans, fix workflows).
+|------|--------------|
+| `references/quick-start.md` | Command-syntax templates |
+| `references/flag-reference.md` | Full flag docs, rule-selector syntax |
+| `references/error-handling.md` | Scan-failure diagnosis |
+| `references/engine-reference.md` | Engine capabilities, file types, rule tags |
+| `references/command-examples.md` | Less-common command scenarios |
+| `references/special-behaviors.md` | SFGE/ApexGuru/AppExchange/diff/large scans |
+| `references/vendor-file-handling.md` | Vendor-file detection and filtering |
+| `references/post-scan-workflows.md` | Steps 7–9 — querying, rule description, rule listing |
+
+`examples/` contains output-structure validation and command patterns (basic/large/security scans, fix workflows).