Minimal Change on the Salesforce Platform

When to use

This skill answers one question: what is the smallest change that fully satisfies the requirement on this platform? It never answers "what is the least work" - the floor below is non-negotiable, and correctness always outranks smallness.

The documented Salesforce order of preference for working with data is itself a ladder: base components built on Lightning Data Service, then LDS wire adapters, then the GraphQL wire adapter, then Apex (Data Guidelines). The rungs below extend that principle to metadata, automation, and integration.

The ladder

Walk the rungs in order. Stop at the first rung that fully satisfies the acceptance criteria. Record the rung you stopped on, and the rung you rejected, in .vibeforce/state/contract.md (format in references/scope-contract.md).

Rung 1 - Does it need to exist?

# Every criterion needs an owner; every artefact needs a criterion.
grep -n "AC-" .vibeforce/state/contract.md

Requirement challenge questions: who consumes the output, what happens if the field is absent, what is the first real record that exercises this, and which existing report or list view already answers the question. If the answer is "the admin might want it later", it is not in scope.

Rung 2 - Does it already exist in this repo or org?

# Repo: fields, classes, flows, permission sets
grep -rn "Region" force-app --include=*.field-meta.xml
ls force-app/main/default/classes | grep -i selector
sf data query --use-tooling-api -q "SELECT QualifiedApiName, DataType, IsCalculated FROM FieldDefinition WHERE EntityDefinition.QualifiedApiName = 'Account'" --target-org vf-dev
sf data query -q "SELECT ApiName, Label, IsActive, ProcessType, TriggerType FROM FlowDefinitionView WHERE IsActive = true" --target-org vf-dev
sf org list metadata --metadata-type ApexClass --target-org vf-dev

EntityDefinition and FieldDefinition are Tooling API objects, so they need --use-tooling-api (Tooling API: EntityDefinition, FieldDefinition). ApexClass, ApexTrigger, PermissionSet, and FlowDefinitionView are standard objects and query without that flag. sf org list metadata requires Modify All Data or Modify Metadata Through Metadata API Functions on the connected user (org list metadata).

Rung 3 - Can platform configuration do it?

Roll-up summary operations are exactly Count, Min, Max, and Sum, with optional summaryFilterItems (CustomField). A validation rule holds a formula that blocks the save and shows an error message when it returns true; since API 20.0 it cannot use compound fields (ValidationRule). Flow choice, ordering, and entry criteria belong to skill sf-flow-automation; sharing and permission design to sf-security-model.

Rung 4 - Is there a standard platform capability?

lightning-record-form, lightning-record-edit-form, and lightning-record-view-form implement Lightning Data Service, need no Apex controller, and enforce field-level security and sharing (Record Form, Record Edit Form). Composite executes up to 25 subrequests as one API call (Composite); Bulk API 2.0 is the documented choice above 2,000 records, and bulkified synchronous calls below it (Bulk API intro).

Rung 5 - Is a framework or dependency already in the project?

grep -rln "fflib_SObjectDomain\|fflib_SObjectSelector\|fflib_ISObjectUnitOfWork" force-app/main/default/classes | head
grep -rln "TriggerHandler\|TriggerDispatcher" force-app/main/default/classes | head
grep -rln "@IsTest" force-app/main/default/classes | xargs -r grep -ln "TestDataFactory\|TestFactory" | head
ls force-app/main/default/lwc | grep -iE "util|helper|common"

When the project is fflib-based, new behaviour goes into the existing layers - see sf-fflib-foundations, sf-fflib-selector-layer, sf-fflib-domain-service-uow, sf-fflib-testing, and sf-fflib-operations. Two conventions in one repo is a defect, not a style preference.

Rung 6 - Can it be one line or one attribute?

<!-- Whole requirement: "Rating must be filled in before save" -->
<lightning-record-edit-form object-api-name="Account" record-id={recordId}>
    <lightning-messages></lightning-messages>
    <lightning-input-field field-name="Rating" required></lightning-input-field>
    <lightning-button type="submit" label="Save"></lightning-button>
</lightning-record-edit-form>

Server-side truth still belongs in a validation rule: the platform documentation recommends validation rules over client-side validation, and the form surfaces those errors automatically (Record Edit Form).

Rung 7 - The minimum custom implementation

Reached only when rungs 1-6 are exhausted and the rejection reason for each is written down. Then the implementation is scoped to the acceptance criteria and nothing else:

• One class per responsibility that the criteria name; no interface without a second implementor.
• One @AuraEnabled method per interaction the UI actually performs; cacheable=true only for reads (AuraEnabled Annotation).
• One SOQL query shaped for the criteria, selective, bulk-safe (skill sf-soql-sosl-optimization).
• Tests for the changed behaviour only (skills sf-apex-testing, sf-lwc-jest-testing).

The floor (never traded for smallness)

Smallness never justifies removing these. Each is a correctness requirement with a concrete platform mechanism.

A change that drops a floor item is not minimal; it is incomplete.

Version boundary: the enforcement mechanisms above are the API 67.0 behaviour (apiVersion in config/vibe-force.defaults.json). Older samples that show WITH SECURITY_ENFORCED predate this boundary and must not be copied.

Read before you decide

The ladder constrains the solution, never the investigation. Choosing a rung without reading the surrounding metadata produces the most expensive kind of small change: one that conflicts with automation that already runs.

Required reading before selecting a rung:

1. Impacted metadata - every file the change would touch, retrieved or grepped, not guessed.
2. Automation inventory on the object - existing triggers, record-triggered Flows and their TriggerOrder, validation rules, duplicate rules, workflow field updates, approval processes.
3. Save-order interactions - whether the proposed rung runs before or after the automation already present, and whether it can re-enter it (skill sf-flow-automation).
4. Existing tests - what currently asserts the behaviour you are about to change; those assertions define the contract you must preserve.
5. Org configuration - permission sets, record types, picklist value sets, and page layouts that already express part of the requirement.

sf data query --use-tooling-api -q "SELECT QualifiedApiName, (SELECT DeveloperName FROM ValidationRules), (SELECT Name FROM ApexTriggers) FROM EntityDefinition WHERE QualifiedApiName = 'Account'" --target-org vf-dev
sf data query -q "SELECT ApiName, Label, TriggerType, RecordTriggerType, TriggerOrder, TriggerObjectOrEventLabel FROM FlowDefinitionView WHERE IsActive = true AND TriggerObjectOrEventLabel = 'Account'" --target-org vf-dev

Wave 0 of the workflow exists for exactly this: sf-scout maps impacted metadata and existing tests before any wave-1 agent edits a file (skill sf-workflow-orchestration).

Over-build catalogue

Anti-patterns

Verification

Minimality is verifiable. Run these before claiming the change is small.

# 1. Shape of the diff: file count and churn per metadata type
git diff --stat
git diff --name-only | sed 's|.*/\([a-z]*\)/[^/]*$|\1|' | sort | uniq -c | sort -rn

# 2. New files are the expensive ones - list them explicitly
git diff --name-status --diff-filter=A

# 3. Dead or duplicated code, unused variables, copy-paste blocks
node "${CLAUDE_PLUGIN_ROOT}/scripts/checks/vf-check.mjs" static --changed

# 4. Full local gate before review
node "${CLAUDE_PLUGIN_ROOT}/scripts/checks/vf-check.mjs" local

# 5. Caller counts for anything newly introduced
grep -rn "AccountRollupService" force-app --include=*.cls | grep -v "AccountRollupService.cls" | wc -l

Code Analyzer ships the engines that catch the mechanical symptoms: pmd for unused code and excessive complexity, cpd for duplicated blocks, eslint for unused JS, flow for Flow issues (Engines). Rule selection and severity gating live in skill sf-code-analyzer-quality; the gate is vf-check analyzer at the configured analyzerFailSeverity.

Scope-versus-criteria checklist:

Review questions to ask on every PR (full list with severities in references/review-checklist.md):

1. Which rung does this stop on, and what was rejected one rung lower?
2. Which acceptance criterion does each new file serve?
3. How many callers does each new class, interface, or module have?
4. Which base component or wire adapter was considered before this custom component?
5. Which declarative option was considered before this Apex?
6. What would break if the newest file were deleted?

Post-deploy, confirm the change did only what it claimed: skill sf-post-deploy-verification with vf-check smoke.

References

• references/declarative-vs-code.md - requirement to declarative option to breaking point to code fallback, with the limits that force code.
• references/base-components-first.md - base Lightning component catalogue, what each handles out of the box, escape hatches, and side-by-side custom-vs-base implementations.
• references/standard-apis-first.md - standard API versus custom Apex REST decision table with limits and sf api request rest examples.
• references/reuse-discovery.md - the repo-and-org discovery playbook: grep patterns, sf commands, Tooling API queries, duplicate-field detection.
• references/scope-contract.md - story to acceptance criteria to .vibeforce/state/contract.md, including the decision-log format.
• references/review-checklist.md - over-build review checklist, severities, per-metadata-type questions, and the evidence to cite.

Official documentation: Data Guidelines, Lightning Data Service, CustomField, ValidationRule, Apex Governor Limits, Composite, Bulk API 2.0, Salesforce CLI Command Reference.