/dx-code-analyzer-custom-rule-create

name: dx-code-analyzer-custom-rule-create
description: "Create custom Code Analyzer rules for Regex (pattern matching), PMD (XPath/AST for Apex and metadata XML), and ESLint (LWC/JavaScript/TypeScript). Use when users want to enforce coding standards, ban patterns, detect hardcoded values, govern metadata, or add rules not in the built-in set. TRIGGER when: user says 'create a rule', 'ban System.debug', 'enforce naming convention', 'detect hardcoded IDs', 'custom rule', 'xpath rule', 'regex rule', 'add a PMD rule', 'enforce a policy', 'create a check for', 'flag this pattern', 'make a rule that catches', 'metadata rule', 'check permissions', 'enforce API version', 'eslint rule', 'lwc rule', 'override rule threshold', 'customize complexity', or describes a pattern to enforce. DO NOT TRIGGER when: user wants to run a scan (use dx-code-analyzer-run), configure engines (use dx-code-analyzer-configure), or explain existing rules (use dx-code-analyzer-run)."
metadata:
  version: "1.0"
  domains: ["Developer Experience"]
  relatedSkills:
    - "dx-code-analyzer-configure"
    - "dx-code-analyzer-run"
  cliTools:
    - tool: ["git"]
      semver: ">=2.0.0"
    - tool: ["node"]
      semver: ">=18.0.0"
    - tool: ["npm"]
      semver: ">=9.0.0"
    - tool: ["sf"]
      semver: ">=2.0.0"

dx-code-analyzer-custom-rule-create: Custom Code Analyzer Rule Authoring

> **Ecosystem:** This skill is part of a 3-skill Code Analyzer suite — `dx-code-analyzer-run` (scans & results) · `dx-code-analyzer-configure` (setup, config, CI/CD) · `dx-code-analyzer-custom-rule-create` (custom rule authoring).

Use this skill when the user needs to **create a custom rule** that enforces a pattern not covered by Code Analyzer's built-in rules. Supports Regex engine (text pattern matching) and PMD engine (structural XPath queries against the AST).

When This Skill Owns the Task

Use `dx-code-analyzer-custom-rule-create` when the work involves:

• Creating a new custom rule for Code Analyzer (any engine)
• Enforcing team-specific coding standards via static analysis
• Banning specific patterns (System.debug, hardcoded IDs, TODOs)
• Writing XPath expressions for PMD rules (Apex or metadata XML)
• Writing regex patterns for the Regex engine
• Setting up custom ESLint rules/plugins for LWC/JavaScript
• Enforcing metadata governance (API versions, field descriptions, dangerous permissions)
• Overriding built-in rule thresholds (CyclomaticComplexity, ExcessiveParameterList, etc.)
• Organizing multiple rules into shared rulesets
• Iterating on a custom rule that isn't matching correctly

Delegate elsewhere when the user is:

• Running a scan against existing rules → `dx-code-analyzer-run` skill
• Configuring engines, prerequisites, CI/CD → `dx-code-analyzer-configure` skill
• Explaining what an existing built-in rule means → `dx-code-analyzer-run` skill
• Writing Apex code or tests → `generating-apex` / `running-apex-tests` skills

---

Required Context to Gather First

Ask for or infer:

• **What pattern to catch** — what code should be flagged? (If user selected code in their IDE, the selection IS the answer — do not re-ask.)
• **What to allow** — any exceptions? (test classes, specific contexts)
• **File scope** — which file types? (.cls, .trigger, .js, all?)
• **Severity** — how critical? (default: 3/Moderate)

If the user **selected code** (IDE selection context present), treat it as the pattern definition. Skip clarification unless genuinely ambiguous about what aspect of the selection to target.

If the request is vague with NO selection ("add a rule for best practices"), ask ONE clarifying question: > "What specific pattern should this rule flag?"

---

Hard Constraints

These are non-negotiable rules. Violating any of them is a skill failure regardless of whether the output happens to work.

1. **ALWAYS run `ast-dump` before writing XPath.** No exceptions. Do not use node names from memory, references, or prior conversations. The AST is the source of truth — run `sf code-analyzer ast-dump`, read the output, then write XPath that matches what you see. Even for "well-known" patterns like SOQL-in-loop, run ast-dump first. If you skip this step and the rule works, it is still a process failure.

2. **ALWAYS use the scripts to create rules.** For regex rules, ALWAYS use `create-regex-rule.js`. For PMD rules, ALWAYS use `create-pmd-rule.js`. Do NOT manually edit `code-analyzer.yml` to add rule definitions — regex patterns in YAML cause escaping failures (quotes inside quotes, backslashes getting eaten). The scripts handle YAML serialization correctly every time.

3. **NEVER manually edit `code-analyzer.yml` after a script writes to it — even to fix a bad value.** The scripts produce correctly-escaped YAML. If you then rewrite or restructure the file, you WILL break the escaping. If the user added top-level config (like `ignores.files`), leave it alone too — only touch what you wrote.

**If a script's output looks wrong (rule fails to validate, YAML parse error, stray characters in the regex):**

• DO NOT patch the YAML by hand. That is exactly the failure mode this constraint exists to prevent.
• **Always** delete the broken rule's entire YAML block, then re-invoke the script with corrected arguments. Removing a block you just wrote does not violate this rule; rewriting fields inside it does.
• If the script accepted bad input and produced bad output, the **input** was wrong (e.g., `--regex "/.../ g"` with a stray space — the flags must be `/g` exactly, no whitespace). Re-invoke with the corrected argument.
• If you genuinely believe the script has a bug, STOP and surface it to the user. Do not hand-edit as a workaround.

4. **`--regex` must be `/pattern/flags` with NO whitespace.** The script trims and validates flags strictly — only `g`, `i`, `m`, `s`, `u`, `y`. `/pat/ g` (with a space) is rejected; so is `/pat/x` (invalid flag) and `/pat/` (no flags). The global flag `g` is mandatory. If vali