handling-sf-data

Salesforce Data Operations Expert (handling-sf-data)

Use this skill when the user needs Salesforce data work: record CRUD, bulk import/export, test data generation, cleanup scripts, or data factory patterns for validating Apex, Flow, or integration behavior.

When This Skill Owns the Task

Use handling-sf-data when the work involves:

• sf data CLI commands
• record creation, update, delete, upsert, export, or tree import/export
• realistic test data generation
• bulk data operations and cleanup
• Apex anonymous scripts for data seeding / rollback

Delegate elsewhere when the user is:

• writing SOQL only → querying-soql
• running or repairing Apex tests → running-apex-tests
• deploying metadata first → deploying-metadata
• creating or modifying custom objects / fields → generating-custom-object or generating-custom-field

Important Mode Decision

Confirm which mode the user wants:

Do not assume remote execution if the user may only want scripts.

Required Context to Gather First

Ask for or infer:

• target object(s)
• org alias, if remote execution is required
• operation type: query, create, update, delete, upsert, import, export, cleanup
• expected volume
• whether this is test data, migration data, or one-off troubleshooting data
• any parent-child relationships that must exist first

Core Operating Rules

• handling-sf-data acts on remote org data unless the user explicitly wants local script generation.
• Objects and fields must already exist before data creation.
• For automation testing, prefer 251+ records when bulk behavior matters.
• Plan cleanup before creating large or noisy datasets — untracked records accumulate across runs and pollute org state.
• Use synthetic, non-identifying data in test records — real PII creates compliance risk and cannot be safely removed after bulk import.
• Prefer CLI-first for straightforward CRUD; use anonymous Apex when the operation truly needs server-side orchestration.

If metadata is missing, stop and hand off to:

• generating-custom-object or generating-custom-field to create the missing schema, then deploying-metadata to deploy it before retrying the data operation

Recommended Workflow

1. Verify prerequisites

Confirm object / field availability, org auth, and required parent records.

2. Run describe-first pre-flight validation when schema is uncertain

Before creating or updating records, use object describe data to validate:

• required fields
• createable vs non-createable fields
• picklist values
• relationship fields and parent requirements

See references/sf-cli-data-commands.md [blocked] for the sf sobject describe command and jq filter patterns for inspecting fields, picklist values, and createable constraints.

3. Choose the smallest correct mechanism

4. Execute or generate assets

Use the built-in templates under assets/ when they fit:

• assets/factories/
• assets/bulk/
• assets/cleanup/
• assets/soql/
• assets/csv/
• assets/json/

5. Verify results

Check counts, relationships, and record IDs after creation or update.

6. Apply a bounded retry strategy

If creation fails:

1. try the primary CLI shape once
2. retry once with corrected parameters
3. re-run describe / validate assumptions
4. pivot to a different mechanism or provide a manual workaround

Do not repeat the same failing command indefinitely.

7. Leave cleanup guidance

Provide exact cleanup commands or rollback assets whenever data was created.

High-Signal Rules

Bulk safety

• use bulk operations for large volumes
• test automation-sensitive behavior with 251+ records where appropriate
• avoid one-record-at-a-time patterns for bulk scenarios

Data integrity

• include required fields
• validate picklist values before creation
• verify parent IDs and relationship integrity
• account for validation rules and duplicate constraints
• exclude non-createable fields from input payloads

Cleanup discipline

Prefer one of:

• delete-by-ID
• delete-by-pattern
• delete-by-created-date window
• rollback / savepoint patterns for script-based test runs

Common Failure Patterns

Output Format

When finishing, report in this order:

1. Operation performed
2. Objects and counts
3. Target org or local artifact path
4. Record IDs / output files
5. Verification result
6. Cleanup instructions

Suggested shape:

Data operation: <create / update / delete / export / seed>
Objects: <object + counts>
Target: <org alias or local path>
Artifacts: <record ids / csv / apex / json files>
Verification: <passed / partial / failed>
Cleanup: <exact delete or rollback guidance>

Cross-Skill Integration

Reference Map

Start here

• references/sf-cli-data-commands.md [blocked]
• references/test-data-best-practices.md [blocked]
• references/orchestration.md [blocked]
• references/test-data-patterns.md [blocked]
• references/test-data-factory-usage.md [blocked]

Query / bulk / cleanup

• references/soql-relationship-guide.md [blocked]
• references/relationship-query-examples.md [blocked]
• references/bulk-operations-guide.md [blocked]
• references/cleanup-rollback-guide.md [blocked]
• references/cleanup-rollback-example.md [blocked]

Examples / limits

• references/crud-workflow-example.md [blocked]
• references/bulk-testing-example.md [blocked]
• references/anonymous-apex-guide.md [blocked]
• references/governor-limits-reference.md [blocked]

Validation scripts

• scripts/soql_validator.py [blocked] — validate SOQL queries before execution
• scripts/validate_data_operation.py [blocked] — pre-flight check for data operations (required fields, picklist values, createable fields)

Asset templates

• assets/factories/ — Apex test data factory scripts (account, contact, opportunity, lead, user, etc.)
• assets/bulk/ — Bulk API 2.0 Apex templates (insert 200, 500, 10000 records; upsert by external ID)
• assets/cleanup/ — Cleanup and rollback scripts (delete by name, date, pattern; transaction rollback)
• assets/soql/ — SOQL query templates (aggregate, subquery, parent-to-child, child-to-parent, polymorphic)
• assets/csv/ — CSV import templates for Account, Contact, Opportunity, custom objects
• assets/json/ — JSON tree import templates (account-contact, account-opportunity, full hierarchy)

Score Guide