Salesforce Advanced Integration Troubleshooting

Overview

Build and falsify layered hypotheses with minimum evidence rather than changing several org, query, permission, or retry variables at once.

Prerequisites

• Basic triage record, exact time window, environment, release, principal, request or job IDs, and current symptom
• Architecture, API and event contracts, object metadata, automation map, limits, deployments, and prior baselines
• Incident commander, application, Salesforce platform, security, data, and vendor support owners

Tool Discipline

Use Read, Glob, and Grep to inspect approved repository and evidence files, WebFetch to re-check current first-party Salesforce documentation, and Write or Edit only for secretless plans, fixtures, configuration, and redacted receipts.

Current Contract

Salesforce diagnostic behavior spans versioned REST responses, debug logs, query feedback, async jobs, event usage, and org configuration. REST query explain is Beta and must be corroborated; diagnostic surface availability varies by entitlement and permission.

Authentication

Use the narrowest diagnostic principal and time window. Never enable broad logging or collect unredacted queries, records, tokens, sessions, org identifiers, or user data without explicit authorization.

Instructions

1. Restate the invariant, symptom, first failure, blast radius, changes, retry history, and what basic triage already ruled out.
2. Construct hypotheses across client, network, OAuth, permission, sharing, metadata, query, automation, lock, limit, async, event, and downstream layers.
3. Collect one discriminating redacted signal per hypothesis using request IDs, logs, limits, job results, metadata fingerprints, and deployment IDs.
4. Use query explain or plan evidence only under its documented status and compare it with representative measured execution.
5. Reproduce with synthetic data or read-only requests, then change one variable at a time under a defined stop condition.
6. Confirm root cause by restoring the invariant with the smallest reversible fix and disproving leading alternatives.
7. Remove trace settings, reconcile affected data or events, publish evidence and uncertainty, and create prevention tests and alerts.

Approval Boundaries

Do not broaden tracing, query sensitive data, change indexes or automation, increase limits, replay work, or reproduce writes in production without owners.

Output

Return the hypothesis table, evidence and timeline, reproduced condition, root cause and confidence, approved fix, reconciliation, cleanup, and prevention work.

Error Handling

Salesforce Integration Architecture Variants

Overview

Produce a falsifiable architecture decision that explains why one interaction pattern fits each use case and which tradeoffs remain.

Prerequisites

• Use cases, business invariants, sources of truth, consumers, latency, volume, ordering, consistency, and recovery needs
• Org products, APIs, events, limits, identities, data classes, residency, retention, support, and existing platforms
• Security, operability, cost, skills, vendor, migration, lock-in, disaster recovery, and change-control constraints

Tool Discipline

Use Read, Glob, and Grep to inspect approved repository and evidence files, WebFetch to re-check current first-party Salesforce documentation, and Write or Edit only for secretless plans, fixtures, configuration, and redacted receipts.

Current Contract

Salesforce documents remote process, batch, data synchronization, and event integration patterns. Direct REST, composite, bulk, Pub/Sub or CDC, middleware, event relay, and replicated read models differ in coupling, consistency, capacity, and recovery.

Authentication

Model client apps, OAuth flows, principals, scopes, CRUD and field access, sharing, secret custody, rotation, revocation, and break-glass separately for every variant.

Instructions

1. Write decision drivers and non-negotiable invariants before naming a preferred technology.
2. Model direct synchronous API, managed or customer middleware, Salesforce events, scheduled bulk, replicated data, and hybrid variants.
3. For each, trace authority, data and event flow, transactions, ordering, idempotency, limits, failure isolation, reconciliation, and recovery.
4. Evaluate security, privacy, residency, audit, operability, latency, throughput, cost, skills, vendor support, and lock-in with evidence.
5. Run threat, failure, capacity, data-correctness, and migration exercises against the leading variants.
6. Prototype the riskiest assumption with synthetic data in the lowest-risk authorized environment.
7. Record the decision, rejected alternatives, evidence, uncertainty, conditions that invalidate it, migration stages, and review date.

Approval Boundaries

Do not select a vendor, create trust, replicate data, establish new system authority, or start production implementation without architecture and owners.

Output

Return the driver matrix, diagrams, variant scores with evidence, prototype result, decision and dissent, risks, migration and rollback plan, and review triggers.

Error Handling

Fork-Safe Salesforce Continuous Integration

Overview

Separate deterministic untrusted-code checks from credentialed org validation so pull requests cannot access Salesforce secrets or mutate a customer org.

Prerequisites

• Repository, Salesforce DX project, package layout, branch policy, and immutable dependency lock
• Synthetic metadata and API fixtures plus an authorized validation org
• CI, Salesforce admin, security, release, and code owners with environment protection rules

Tool Discipline

Use Read, Glob, and Grep to inspect approved repository and evidence files, WebFetch to re-check current first-party Salesforce documentation, and Write or Edit only for secretless plans, fixtures, configuration, and redacted receipts.

Current Contract

Salesforce CLI can validate and deploy source against authorized orgs, but exact commands, test levels, authentication, and metadata behavior vary with the pinned CLI and project. Fork pull requests must be treated as untrusted.

Authentication

Keep org authorization, certificates, secrets, and aliases out of fork-origin jobs, logs, caches, and artifacts. Resolve protected credentials only after trusted code, environment approval, and exact-head verification.

Instructions

1. Pin runtime, package manager, Salesforce CLI, plugins, lockfiles, action SHAs, and generated-artifact checks.
2. Create a secretless lane for formatting, linting, static analysis, unit tests, schema tests, fixture contracts, and source validation.
3. Model auth expiry, permission denial, API-version drift, metadata conflict, partial deployment, limits, and rollback in fixtures.
4. Restrict credentialed jobs to protected branches or environments with no fork secrets, minimal permissions, concurrency, and timeouts.
5. Against an approved non-production org, verify identity, validate the bounded deployment, run required tests, and capture IDs.
6. Require human approval and immutable artifact promotion before any production validation or deployment job.
7. Reconcile deployed metadata and application health, publish a redacted receipt, and revoke temporary credentials.

Approval Boundaries

Do not expose secrets to pull requests, authenticate unreviewed code, auto-deploy to production, or lower required test levels or branch protection.

Output

Return the trust-boundary diagram, pinned CI configuration, secretless and protected gate results, org identity proof, validation IDs, promotion approval, and rollback evidence.

Error Handling

Salesforce Integration Error Triage

Overview

Classify the failed layer, preserve request context, and test one evidence-backed hypothesis before proposing a bounded, reversible correction.

Prerequisites

• Timestamp, environment, principal, operation, request or job ID, and redacted response
• Expected API version, object and field contract, permissions, limits, automation, and recent changes
• Incident, application, Salesforce platform, security, and data owners

Tool Discipline

Use Read, Glob, and Grep to inspect approved repository and evidence files, WebFetch to re-check current first-party Salesforce documentation, and Write or Edit only for secretless plans, fixtures, configuration, and redacted receipts.

Current Contract

Salesforce exposes documented HTTP and API errors, but the same symptom can originate from OAuth, permissions, sharing, schema, validation, automation, locks, limits, asynchronous processing, or event state. Diagnose the returned evidence in org context.

Authentication

Use read-only diagnostic access with the approved principal or a separately authorized support principal. Do not collect tokens, session IDs, passwords, private keys, raw personal data, or broad debug logs.

Instructions

1. Freeze the first failure timestamp, environment, release, principal, API, request or job ID, payload shape, and retry history.
2. Confirm org status, identity, API support, resource entitlement, and whether other integrations are affected.
3. Classify the layer: transport, OAuth, scope, CRUD or field access, sharing, schema, validation, automation, locking, limit, async job, or event.
4. Correlate the minimum Salesforce response, application trace, limits snapshot, metadata, job result, and recent change evidence.
5. Reproduce with a synthetic or read-only request in the lowest-risk authorized org.
6. Propose one hypothesis-specific correction and define success, stop, rollback, and no-blind-retry rules.
7. Apply only after approval, verify the original invariant, and document prevention and monitoring changes.

Approval Boundaries

Do not reset credentials, broaden permissions, disable automation, alter records, increase capacity, or replay writes as a diagnostic shortcut.

Output

Return the incident frame, classified layer, evidence timeline, ruled-out causes, root or leading cause, approved action, verification, and prevention owner.

Error Handling

Governed Salesforce Record and SOQL Workflow

Overview

Turn a record request into a permission-aware, selective, idempotent, and auditable operation instead of embedding fixed object assumptions.

Prerequisites

• Authorized org, object, business purpose, selection rule, and data owner
• Current object metadata, CRUD and field access, sharing context, automation, and duplicate rules
• Expected counts, external keys, mutation policy, rollback method, and reconciliation owner

Tool Discipline

Use Read, Glob, and Grep to inspect approved repository and evidence files, WebFetch to re-check current first-party Salesforce documentation, and Write or Edit only for secretless plans, fixtures, configuration, and redacted receipts.

Current Contract

REST and SOQL operations are versioned and execute in the security context of the authorized principal. Object metadata, fields, validation, triggers, flows, sharing, and duplicate behavior vary by org.

Authentication

Use the approved integration principal and OAuth contract. Prove object and field access for that principal; do not infer authorization from an administrator session or from metadata visible to another user.

Instructions

1. Record the business invariant, org, object, fields, predicates, expected count, external key, and accountable owner.
2. Discover a supported API version and inspect current object and field metadata for the principal.
3. Build a selective parameterized query with explicit fields, scope, ordering, row bound, and pagination plan.
4. Run a read-only sample and compare counts, ownership, duplicates, nullability, and sensitive-data classification.
5. Preview create, update, upsert, or delete effects including validation, automation, sharing, and downstream integrations.
6. After explicit approval, execute a bounded idempotent batch and retain request and result identifiers without record data.
7. Re-query by stable key, reconcile success and failure counts, quarantine exceptions, and invoke rollback if invariants fail.

Approval Boundaries

Do not mutate records, bypass validation, use broad queries, change sharing, or expose field values without object, data, and change-owner approval.

Output

Return the query and metadata evidence, expected and actual counts, permission findings, mutation preview, request IDs, exceptions, reconciliation, and rollback status.

Error Handling

Salesforce High-Volume and Composite Operation

Overview

Choose an API from workload evidence, make every batch restartable, and prove final state across partial, asynchronous, and dependent outcomes.

Prerequisites

• Dataset classification, object dependencies, operation, expected counts, external IDs, and owners
• Current Bulk API 2.0, Composite, Graph, and sObject Collections documentation
• Org limits, automation cost, error budget, maintenance window, quarantine, and rollback plans

Tool Discipline

Use Read, Glob, and Grep to inspect approved repository and evidence files, WebFetch to re-check current first-party Salesforce documentation, and Write or Edit only for secretless plans, fixtures, configuration, and redacted receipts.

Current Contract

Bulk API 2.0 performs asynchronous CSV ingest and large queries. Composite APIs combine supported REST subrequests with documented dependency and limit semantics; the best choice depends on volume, dependency graph, latency, and atomicity needs.

Authentication

Use a dedicated approved principal with only the required API, object, and field permissions. Keep tokens and payload data out of logs, plans, fixtures, and support bundles.

Instructions

1. Profile row count, payload size, dependencies, ordering, latency, atomicity, retry, and reconciliation requirements.
2. Inspect org entitlements, current API versions, limits, object metadata, automation, external IDs, and lock risks.
3. Select Bulk API 2.0 for suitable asynchronous volume or the documented Composite resource for bounded dependent requests.
4. Normalize and validate data, split deterministic batches, assign stable source keys, and create a quarantine ledger.
5. Run a synthetic or read-only proof, then a small approved non-production write canary.
6. Execute within the approved capacity window while recording job, graph, batch, request, and result identifiers.
7. Download successes and failures, re-query target state, reconcile counts and keys, and retry only classified safe subsets.

Approval Boundaries

Do not start high-volume jobs, select serial or parallel behavior, bypass automation, or retry uncertain writes without data, platform, and change-owner approval.

Output

Return the API decision, capacity plan, batch manifest, job identifiers, success and failure ledgers, reconciliation evidence, and rollback or resume point.

Error Handling

Salesforce Cost and Value Governance

Overview

Build a dated total-cost model that connects commercial terms and technical consumption to business outcomes without inventing public prices or savings.

Prerequisites

• Current order forms, invoices, license assignments, add-ons, storage, support, and vendor or partner statements
• Org usage, API and event allocations, middleware, compute, operations, incident, and migration evidence
• Finance, procurement, Salesforce platform, security, data, architecture, and business owners

Tool Discipline

Use Read, Glob, and Grep to inspect approved repository and evidence files, WebFetch to re-check current first-party Salesforce documentation, and Write or Edit only for secretless plans, fixtures, configuration, and redacted receipts.

Current Contract

Salesforce editions, licenses, add-ons, storage, event delivery, API allocations, support, and partner services are customer-specific and change over time. Public documentation cannot establish one customer's price or entitlement.

Authentication

Use read-only approved billing, contract, org, and telemetry evidence. Separate commercial and technical access and do not expose user-level license, compensation, customer, or record data.

Instructions

1. Freeze review window, currencies, orgs, products, contracts, populations, workloads, outcomes, and accountable owners.
2. Reconcile invoices and commitments with assigned and active licenses, storage, API and event usage, add-ons, support, middleware, compute, and labor.
3. Normalize time periods and currencies while preserving source, effective date, allocation method, and confidence.
4. Identify unused or mismatched assignments, duplicate capability, retention growth, event or API pressure, support load, and architectural overhead.
5. Model bounded scenarios with commercial assumptions, technical effects, business impact, security and data risk, reversibility, and confidence.
6. Present license, contract, retention, integration, scheduling, or architecture changes to the corresponding owners.
7. Canary reversible operational changes, reconcile savings and outcomes, and never claim savings until invoices and service quality confirm them.

Approval Boundaries

Do not remove licenses, change contracts, delete data, reduce support, throttle business-critical work, or re-architect integrations without owners.

Output

Return the reconciled baseline, dated sources, allocation model, anomalies, scenarios, assumptions, approvals, canary evidence, realized-versus-forecast result, and review date.

Error Handling

Salesforce Data Handling and Privacy Operations

Overview

Translate policy and legal obligations into object- and field-level controls without treating one Salesforce feature or object as automatic compliance.

Prerequisites

• Dataset, objects, fields, data subjects, purposes, jurisdictions, systems of record, recipients, and owners
• Current object metadata, CRUD and field access, sharing, encryption, retention, audit, export, and deletion capabilities
• Privacy policy, legal basis, subject-request process, legal holds, incident process, and evidence requirements

Tool Discipline

Use Read, Glob, and Grep to inspect approved repository and evidence files, WebFetch to re-check current first-party Salesforce documentation, and Write or Edit only for secretless plans, fixtures, configuration, and redacted receipts.

Current Contract

Salesforce provides data, security, privacy, encryption, and metadata capabilities that vary by product and entitlement. The Individual object can support privacy use cases where enabled, but its presence alone does not prove GDPR, CCPA, retention, or subject-request compliance.

Authentication

Use minimum object, field, record, and export access for the approved purpose. Separate administrators, privacy operators, integration principals, and support access; never place tokens or raw personal data in fixtures, logs, or receipts.

Instructions

1. Map objects and fields to data classes, purposes, legal bases, subjects, sources of truth, recipients, residency, retention, and owners.
2. Discover current metadata, permissions, sharing, encryption, audit, Individual-object or alternative mapping, and downstream copies.
3. Minimize selected fields and rows, parameterize queries, redact logs, encrypt transport and storage, and restrict exports.
4. Define correction, access, portability, restriction, deletion, anonymization, and legal-hold actions across every authoritative and copied system.
5. Use stable case identifiers and approval gates; never assume deleting one Salesforce record satisfies a multi-system request.
6. Test the workflow with synthetic subjects, inaccessible fields, holds, duplicates, relationships, events, backups, and failures.
7. Execute approved cases, reconcile every system and exception, retain minimum evidence, and delete temporary exports on schedule.

Approval Boundaries

Do not export, disclose, correct, merge, anonymize, delete, unencrypt, shorten retention, or override a legal hold without accountable approval.

Output

Return the data map, control and permission evidence, minimum query or export contract, case plan, approvals, system results, exceptions, reconciliation, and expiry.

Error Handling

Privacy-Safe Salesforce Support Evidence Bundle

Overview

Collect the smallest reproducible evidence set while excluding credentials, raw business records, personal data, and unrelated org configuration.

Prerequisites

• Incident identifier, time window, environment, affected operation, and support destination
• Approved evidence classes, redaction policy, retention period, and transfer channel
• Read-only access to the specific limits, metadata, job, event, or log evidence required

Tool Discipline

Use Read, Glob, and Grep to inspect approved repository and evidence files, WebFetch to re-check current first-party Salesforce documentation, and Write or Edit only for secretless plans, fixtures, configuration, and redacted receipts.

Current Contract

Salesforce diagnostic surfaces vary by product, edition, permission, and entitlement. Limits can be read through the versioned REST resource, while debug logs, Event Monitoring, async jobs, and event metrics require separate access and interpretation.

Authentication

Use a dedicated read-only diagnostic principal where possible. Never include access or refresh tokens, session IDs, cookies, authorization headers, client secrets, private keys, usernames, org IDs unless approved, or raw record payloads.

Instructions

1. Create a manifest naming incident, time window, environment class, components, evidence owners, retention, and recipient.
2. Collect application version, dependency lock, API version, redacted request ID, status, timing, retry history, and recent deployment IDs.
3. Add only relevant limits, object metadata fingerprints, async job summaries, event channel metrics, and log excerpts.
4. Replace record IDs, user IDs, org IDs, domains, field values, queries, and payloads with stable redaction tokens where required.
5. Scan the bundle for credentials, authorization material, personal data, customer names, and unrelated records.
6. Generate hashes and a manifest, then have the incident and data owners review the exact archive.
7. Transfer through the approved support channel, record receipt, expiry, and deletion responsibility.

Approval Boundaries

Do not enable broad tracing, extend log retention, retrieve EventLogFile content, export records, or send an archive without support, security, and data-owner approval.

Output

Return the redacted manifest, evidence inventory, collection gaps, hashes, reviewer approvals, transfer receipt, retention deadline, and deletion owner.

Error Handling

Salesforce-Connected Application Deployment

Overview

Release customer-owned adapter code independently of Salesforce metadata while proving the target org, secrets, API contract, and business invariants.

Prerequisites

• Immutable application artifact, source commit, dependency lock, SBOM or equivalent inventory, and deployment target
• Approved Salesforce app and principal, target-org identity, supported API contract, and secret references
• Preview environment, canary, health and business checks, capacity budget, rollback, and incident owners

Tool Discipline

Use Read, Glob, and Grep to inspect approved repository and evidence files, WebFetch to re-check current first-party Salesforce documentation, and Write or Edit only for secretless plans, fixtures, configuration, and redacted receipts.

Current Contract

A Salesforce-connected application may run on many compute platforms; Salesforce does not define one universal deployment target. The application must bind to the customer-approved org, OAuth app, API version, limits, schema, and event contract.

Authentication

Inject only secret references through the target platform after environment approval. Never bake Salesforce tokens, keys, usernames, org IDs, or production domains into images, frontend bundles, build logs, or artifacts.

Instructions

1. Freeze the artifact digest, source SHA, dependencies, configuration schema, Salesforce API contract, and migration set.
2. Verify target environment, org identity expectation, app type, principal, scopes, permissions, secret references, egress, and observability.
3. Deploy to preview with synthetic Salesforce fixtures and prove startup, health, timeout, redaction, idempotency, and rollback.
4. With approval, bind an authorized sandbox and run read-only plus bounded mutation contract checks.
5. Define production canary percentage or workload, time box, stop signals, shared-limit budget, and reconciliation queries.
6. Promote the same artifact, verify org identity before traffic, monitor technical and business invariants, and halt on breach.
7. Reconcile outcomes, complete or rollback, revoke temporary access, and record artifact, deployment, and verification IDs.

Approval Boundaries

Do not deploy a different artifact, inject production secrets, route production traffic, run migrations, or expand a canary without named approval.

Output

Return artifact and environment identity, configuration contract, sandbox proof, canary plan, deployment IDs, signals, reconciliation, rollback status, and owners.

Error Handling

Salesforce Enterprise Access and Sharing Governance

Overview

Build least privilege from job and workload needs through app authorization, org permissions, object and field access, record sharing, and periodic review.

Prerequisites

• Personas and integration workloads, business functions, data classes, orgs, environments, and owners
• Current profiles, permission sets and groups, licenses, roles, sharing defaults and rules, field access, queues, and app policies
• Identity lifecycle, SSO and MFA, privileged access, break-glass, segregation, recertification, and audit requirements

Tool Discipline

Use Read, Glob, and Grep to inspect approved repository and evidence files, WebFetch to re-check current first-party Salesforce documentation, and Write or Edit only for secretless plans, fixtures, configuration, and redacted receipts.

Current Contract

Salesforce authorization is layered: identity and app policy, license and profile baseline, permission sets or groups, object CRUD, field access, record sharing, and contextual controls. Effective access must be measured in the target org and user context.

Authentication

Separate human, integration, deployment, monitoring, support, and break-glass principals. Bind each to approved SSO or OAuth policy, minimum scope, lifecycle, rotation or recertification, revocation, and audit evidence.

Instructions

1. Define personas and workloads with allowed actions, data, records, environments, hours, and business owners.
2. Inventory effective licenses, profiles, permissions, permission-set groups, roles, sharing defaults and rules, field access, and client apps.
3. Build an entitlement matrix from business need to effective access and identify inherited, overlapping, elevated, dormant, and conflicting grants.
4. Design the minimum profile baseline plus permission sets or groups and record-sharing model; keep integration access separate from users.
5. Test allowed and denied object, field, record, API, event, export, deployment, and admin paths with representative principals.
6. Present assignment, removal, sharing, SSO, app-policy, and break-glass changes for approval and canary them in non-production.
7. Recalculate effective access, review logs, revoke obsolete grants, and schedule owner-attested recertification.

Approval Boundaries

Do not assign licenses, permissions, groups, roles, sharing rules, app access, SSO policy, or privileged roles without identity, admin, security, and data owners.

Output

Return the persona matrix, effective-access inventory, gaps and conflicts, target model, denied-path tests, approved changes, revocation proof, and recertification schedule.

Error Handling

Salesforce Read-Only Capability Proof

Overview

Prove the selected principal, org, API version, object entitlement, and field visibility before any record mutation is considered.

Prerequisites

• An authorized non-production org and secret reference
• Expected org identity, principal, object, fields, and business owner
• Current REST API and authorization documentation

Tool Discipline

Use Read, Glob, and Grep to inspect approved repository and evidence files, WebFetch to re-check current first-party Salesforce documentation, and Write or Edit only for secretless plans, fixtures, configuration, and redacted receipts.

Current Contract

The REST Versions resource lets a client discover versions instead of hard-coding one. Resources, objects, fields, CRUD, sharing, and limits remain org- and principal-specific.

Authentication

Use the approved OAuth client and principal from the onboarding decision. Keep access and refresh tokens out of commands, files, prompts, logs, screenshots, and receipts.

Instructions

1. Record the expected org, environment, principal, My Domain, object, fields, and success criteria.
2. Resolve credentials only through the approved secret mechanism and verify the returned org identity.
3. List supported REST versions and select a supported version allowed by the customer contract.
4. Discover available resources, then inspect object metadata and field accessibility for the intended read.
5. Run one bounded read-only query with non-sensitive fields and an explicit row limit.
6. Preview any proposed create or update with validation, duplicate, automation, ownership, and rollback effects.
7. Return a redacted receipt and request separate approval before executing a mutation.

Approval Boundaries

Do not create, update, delete, undelete, merge, or expose records during the proof. Any mutation requires object-owner approval and a recoverable test case.

Output

Return org and principal verification, selected API version, visible resource and field evidence, query result counts, mutation preview, and next approval.

Error Handling

Example

A redacted completion receipt might look like this:

…

Salesforce Integration Incident Response

Overview

Restore business invariants safely by separating Salesforce platform state, customer org state, application behavior, data correctness, and event delivery.

Prerequisites

• Incident commander, severity model, affected environments and workloads, communications, and evidence channel
• Current deployment, org identity, app and principal, API, limits, jobs, events, data, and reconciliation contracts
• Pre-approved containment, failover, deferral, rollback, credential revocation, and vendor escalation procedures

Tool Discipline

Use Read, Glob, and Grep to inspect approved repository and evidence files, WebFetch to re-check current first-party Salesforce documentation, and Write or Edit only for secretless plans, fixtures, configuration, and redacted receipts.

Current Contract

Salesforce Status reports platform incidents, while org-specific authorization, limits, metadata, automation, jobs, events, and data can fail independently. A green platform status does not prove an integration or business invariant is healthy.

Authentication

Use read-only incident access first and separate break-glass access under the customer process. Never paste tokens, sessions, private keys, raw records, or unrestricted logs into tickets or chat.

Instructions

1. Declare severity, commander, time window, affected orgs and workloads, business invariant, data risk, and communication cadence.
2. Freeze deployments and unsafe retries; preserve request, job, event, deployment, and reconciliation identifiers.
3. Check Salesforce Status, org identity, authorization, API support, limits, metadata, automation, async jobs, event flow, and application telemetry.
4. Classify platform, org, identity, permission, schema, capacity, code, dependency, data, or consumer failure and bound impact.
5. Select the least-destructive approved containment such as pausing intake, deferring work, isolating a consumer, rollback, or credential revocation.
6. Recover in a bounded cohort, reconcile records and events by stable keys, and monitor technical and business stop signals.
7. Close only after invariants, backlog, security, and data exposure are resolved; assign root-cause and prevention work.

Approval Boundaries

Do not rotate credentials, broaden access, disable automation, replay events, retry writes, purge queues, roll back, or fail over without incident and system owners.

Output

Return severity, timeline, evidence, classification, containment, approved actions, recovery IDs, reconciliation, exposure assessment, communications, and prevention owners.

Error Handling

Salesforce API Authorization and Client-App Onboarding

Overview

Choose the app and OAuth model, establish least privilege, and prove read-only access without defaulting to legacy username-password automation.

Prerequisites

• Target org, edition, domain, environment, integration purpose, and data classes
• Identity, security, Salesforce administration, application, and support owners
• Current org policy and first-party OAuth documentation

Tool Discipline

Use Read, Glob, and Grep to inspect approved repository and evidence files, WebFetch to re-check current first-party Salesforce documentation, and Write or Edit only for secretless plans, fixtures, configuration, and redacted receipts.

Current Contract

Salesforce REST API supports OAuth through External Client Apps or Connected Apps. Creating Connected Apps is restricted as of Spring '26; existing Connected Apps can continue, while Salesforce recommends External Client Apps for new integrations.

Authentication

Select an OAuth flow from current Salesforce documentation for the workload and client type. Never copy browser sessions, use a human password in automation, log tokens, or assume that one flow, scope set, or login host fits every org.

Instructions

1. Record the org, My Domain, edition, environment, workload, required resources, and accountable owners.
2. Determine whether the org requires an External Client App or has an approved existing Connected App.
3. Map the selected OAuth flow, scopes, policies, principal, certificate or secret custody, expiry, rotation, and revocation.
4. Inspect the repository for password flows, unpinned login hosts, broad scopes, plaintext keys, and mixed-org aliases.
5. Present app creation, policy, permission-set assignment, pre-authorization, and credential issuance for explicit approval.
6. After provisioning, discover supported API versions and run the smallest documented read-only identity or resource check.
7. Store only secret references and a redacted receipt; test revocation and recovery in a non-production org.

Approval Boundaries

Do not create or alter a client app, grant scopes, assign permissions, issue credentials, or test production writes without the named org and security owners.

Output

Return the app-type decision, OAuth contract, access matrix, secret references, read-only verification, rotation and revocation owners, and unresolved policy questions.

Error Handling

Salesforce Integration Pitfall Audit

Overview

Find evidence of recurring failure patterns in code and operations, rank their real blast radius, and convert each confirmed issue into a bounded fix and regression test.

Prerequisites

• Repository, architecture, org topology, API and event contracts, deployment history, incidents, and current owners
• Current Salesforce API EOL, OAuth, limits, metadata, security, Bulk, Composite, CDC or Pub/Sub documentation
• Representative fixtures, non-production org, policy gates, reconciliation queries, and change process

Tool Discipline

Use Read, Glob, and Grep to inspect approved repository and evidence files, WebFetch to re-check current first-party Salesforce documentation, and Write or Edit only for secretless plans, fixtures, configuration, and redacted receipts.

Current Contract

Common Salesforce defects cross application and org boundaries: unsupported versions, legacy auth, inefficient queries, shared capacity, object or field drift, automation side effects, partial writes, event gaps, and permission differences. Their exact behavior must be proven in context.

Authentication

Audit secret references and authorization boundaries without resolving live secrets. Use the real integration principal only in a protected authorized test lane, never an administrator session as proof.

Instructions

1. Inventory hard-coded API versions, login hosts, app types, OAuth flows, secrets, org aliases, direct calls, queries, writes, retries, and event state.
2. Detect N-plus-one and unbounded queries, broad field selection, missing pagination, stale metadata, wrong API mode, and unmeasured automation.
3. Check shared limits, concurrency, hard-quota behavior, timeout classification, partial results, uncertain-write reconciliation, and batch idempotency.
4. Review CRUD and field access, sharing, SOQL construction, logs, exports, support bundles, production data in fixtures, and privileged bypasses.
5. Inspect event schemas, checkpoints, duplicates, ordering, gap and overflow handling, dead letters, reconciliation, and backfill.
6. Rank confirmed findings by exploitability, data and business impact, likelihood, detectability, and recovery cost.
7. Remediate one boundary at a time with negative fixtures, protected canaries, rollback, and invariant reconciliation.

Approval Boundaries

Do not resolve findings by broadening permissions, disabling automation, increasing retries, raising concurrency, resetting checkpoints, or deleting data without owners.

Output

Return the pitfall inventory, evidence and severity, false positives, prioritized fixes, tests, canary and rollback plans, reconciliation, and owners.

Error Handling

Salesforce Bounded Load and Scale Validation

Overview

Measure useful throughput and failure behavior without treating Salesforce as an unconstrained HTTP endpoint or using production records as test data.

Prerequisites

• Representative workload mix, service objectives, business invariants, expected growth, and capacity owner
• Dedicated authorized org, synthetic dataset, matching automation where possible, current limits, and peer-workload schedule
• Load stages, concurrency ceilings, stop thresholds, cleanup, reconciliation, and incident contacts

Tool Discipline

Use Read, Glob, and Grep to inspect approved repository and evidence files, WebFetch to re-check current first-party Salesforce documentation, and Write or Edit only for secretless plans, fixtures, configuration, and redacted receipts.

Current Contract

Salesforce enforces org-, edition-, license-, API-, Apex-, bulk-, event-, and concurrency-dependent limits. Limits and usage must be discovered in the target org, and non-production fidelity to production must be documented.

Authentication

Use a dedicated non-production principal with minimum objects and fields. Keep authorization outside load scripts and prevent tools, results, and fixtures from containing production tokens or personal data.

Instructions

1. Model read, write, query, bulk, composite, async, and event workload proportions plus business deadlines and growth.
2. Capture org identity, edition, features, metadata, automation, relevant limits, peer workloads, and fidelity gaps.
3. Generate synthetic records with stable keys and safe relationships; precompute expected counts and outcomes.
4. Define stepped load, warm-up, duration, concurrency, request budget, stop thresholds, cooldown, cleanup, and rollback.
5. Run small stages while measuring latency, throughput, errors, limits, locks, async lag, event lag, automation, and business outcomes.
6. Stop on the first approved threshold; never retry hard limits or uncertain writes as additional load.
7. Reconcile all generated data and events, delete fixtures, restore settings, compare capacity to objectives, and state extrapolation limits.

Approval Boundaries

Do not point load tools at production, use real customer data, exceed the approved budget, disable automation, or raise concurrency after a breach.

Output

Return the workload model, org and fidelity evidence, synthetic dataset, stage results, thresholds, bottleneck, invariant checks, cleanup, and capacity recommendation.

Error Handling

Salesforce DX Local Development Loop

Overview

Create a source-driven loop that separates static and synthetic checks from explicitly authorized org validation and leaves no unmanaged test data.

Prerequisites

• A Salesforce DX project or an approved migration plan to source format
• An authorized Dev Hub and scratch-org definition, or a dedicated development sandbox
• Synthetic fixtures, test owner, cleanup policy, and current Salesforce CLI contract

Tool Discipline

Use Read, Glob, and Grep to inspect approved repository and evidence files, WebFetch to re-check current first-party Salesforce documentation, and Write or Edit only for secretless plans, fixtures, configuration, and redacted receipts.

Current Contract

Salesforce DX supports source-driven development and scratch orgs configured through project definitions; org availability, features, limits, duration, namespaces, and sandbox alternatives depend on the customer environment.

Authentication

Use a named CLI alias backed by the approved OAuth path. Never commit authorization files, access tokens, private keys, usernames, org IDs, or generated user passwords.

Instructions

1. Inspect project configuration, package directories, metadata ownership, API versions, hooks, and current CLI pin.
2. Choose a scratch org or development sandbox based on feature fidelity, data need, namespace, and lifecycle constraints.
3. Create synthetic fixtures and local contract tests that require no live org or secret.
4. Run formatting, static analysis, unit tests, schema checks, and metadata dependency checks locally.
5. With approval, create or authenticate the development org and deploy only the bounded source set.
6. Run Apex, Flow, Lightning, and integration tests applicable to the change; capture aggregate results and IDs only.
7. Delete synthetic data, close or expire temporary orgs, revoke temporary access, and record reproducible commands.

Approval Boundaries

Do not create orgs, enable features, deploy metadata, load data, or change remote configuration without Dev Hub, admin, and component-owner approval.

Output

Return the environment decision, pinned toolchain, source and fixture map, local and org test results, cleanup receipt, and remaining fidelity gaps.

Error Handling

Salesforce Governed Data Migration

Overview

Move data as a controlled accounting exercise in which every source key, transformation, dependency, target result, exception, and rollback obligation is traceable.

Prerequisites

• Source and target systems, objects, owners, data classes, migration scope, cutover window, and success criteria
• Current source schema, Salesforce metadata, external IDs, relationships, validation, automation, sharing, and limits
• Mapping and transform rules, quality thresholds, quarantine, reconciliation, rollback or compensating action, and retention plan

Tool Discipline

Use Read, Glob, and Grep to inspect approved repository and evidence files, WebFetch to re-check current first-party Salesforce documentation, and Write or Edit only for secretless plans, fixtures, configuration, and redacted receipts.

Current Contract

Bulk API 2.0 supports asynchronous CSV ingest and query, including insert, update, upsert, and delete where documented and entitled. Data Loader and other tools have separate contracts; object behavior, automation, and limits remain org-specific.

Authentication

Separate source read, transformation, target write, verification, and support access. Keep tokens and private keys out of migration files; encrypt and expire approved extracts and restrict raw personal data.

Instructions

1. Freeze scope, source snapshot or watermark, objects, fields, filters, counts, classifications, owners, and cutover criteria.
2. Profile data quality and map source keys, target external IDs, required fields, lookups, parents, children, owners, picklists, and transforms.
3. Discover target API versions, metadata, permissions, sharing, validation, automation, duplicate rules, storage, limits, and lock behavior.
4. Order deterministic migration waves, create immutable manifests and hashes, and separate valid, rejected, and quarantined records.
5. Run dry-run transformations, then small synthetic and representative non-production canaries with full dependency reconciliation.
6. Execute approved production waves within limits; preserve job IDs and result files and never blindly replay uncertain batches.
7. Re-query by stable keys, reconcile counts, values, relationships, ownership, duplicates, and downstream effects; cut over or roll back.

Approval Boundaries

Do not extract production data, disable automation, change external IDs, overwrite owners, delete records, start a load, or cut over without owners.

Output

Return scope and snapshot, mappings, quality report, dependency graph, manifests, job results, quarantine, reconciliation, cutover decision, rollback, and expiry.

Error Handling

Salesforce Multi-Environment and Org Topology

Overview

Map each environment to a purpose, fidelity level, data policy, authorization boundary, lifecycle, and promotion contract.

Prerequisites

• Business release model, Salesforce DX project, package strategy, org inventory, and environment owners
• Dev Hub, scratch-org, sandbox, staging, and production capabilities actually available to the customer
• Data seeding, masking, refresh, drift, namespace, dependency, promotion, rollback, and support requirements

Tool Discipline

Use Read, Glob, and Grep to inspect approved repository and evidence files, WebFetch to re-check current first-party Salesforce documentation, and Write or Edit only for secretless plans, fixtures, configuration, and redacted receipts.

Current Contract

Scratch orgs are disposable source-driven environments configured from project definitions; sandboxes provide different production fidelity and lifecycle characteristics. Available types, features, refreshes, data, and limits depend on the customer org.

Authentication

Give each environment separate aliases, apps or policies, principals, permissions, and secret references. Never copy production tokens or unmasked production data into development or CI.

Instructions

1. Inventory every org and environment with purpose, edition, features, packages, namespace, data class, owner, lifecycle, and authority.
2. Choose scratch org, developer sandbox, partial or full sandbox, or other approved environment from fidelity and data requirements.
3. Define source, metadata, package, settings, seed, masking, and post-refresh automation contracts.
4. Create environment-specific app, principal, permission, limit, event, endpoint, and secret-reference matrices.
5. Automate deterministic creation or refresh where supported, then verify org identity before any deployment or data load.
6. Promote immutable source and artifacts through validation gates; never promote mutable org state as the source of truth.
7. Detect configuration and metadata drift, reconcile approved exceptions, test rollback, and retire environments and credentials on schedule.

Approval Boundaries

Do not create, refresh, clone, seed, mask, deploy, or retire an org without Dev Hub, admin, security, privacy, data, and release approval.

Output

Return the org topology, fidelity and data matrix, lifecycle, configuration contract, authorization map, promotion gates, drift report, and retirement owners.

Error Handling

Salesforce Integration Observability and Reconciliation

Overview

Connect technical telemetry to Salesforce platform state and business correctness without exporting sensitive records into monitoring systems.

Prerequisites

• System context, service and business objectives, APIs, jobs, event channels, orgs, and owners
• Current Salesforce Status, Limits, EventLogFile or entitled Event Monitoring, async-job, and event-usage surfaces
• Telemetry data classification, redaction, retention, alert routing, incident, and reconciliation policies

Tool Discipline

Use Read, Glob, and Grep to inspect approved repository and evidence files, WebFetch to re-check current first-party Salesforce documentation, and Write or Edit only for secretless plans, fixtures, configuration, and redacted receipts.

Current Contract

Salesforce Status, REST limits, response headers, async jobs, platform-event usage, debug logs, and Event Monitoring expose different signals with different entitlements and delays. Limits resource values can lag recent consumption.

Authentication

Use separate read-only monitoring access with minimum permissions. Never emit access tokens, session IDs, authorization headers, raw SOQL results, record payloads, or unrestricted user and org identifiers as telemetry.

Instructions

1. Define availability, latency, throughput, error, freshness, completeness, duplicate, limit, job, event-lag, and business-invariant objectives.
2. Instrument the adapter with redacted request IDs, operation class, API version, timing, outcome, retry, and reconciliation state.
3. Collect Salesforce platform status, relevant limit and header values, async job summaries, event metrics, and entitled logs.
4. Normalize timestamps, org and environment aliases, deployment IDs, and correlation IDs without exposing customer record data.
5. Build dashboards by environment and workload with freshness labels and separate technical from business-correctness views.
6. Alert on sustained objective breaches, capacity margin, auth failure, job failure, event gap, wrong-org binding, and reconciliation mismatch.
7. Test alerts and runbooks in non-production, measure noise and blind spots, and assign review and retention owners.

Approval Boundaries

Do not enable broad logging, retrieve sensitive event files, expand retention, export record data, or create production alerts without security, admin, and incident-owner approval.

Output

Return the signal catalog, instrumentation contract, dashboards, alerts, redaction and retention rules, runbook links, test receipt, blind spots, and owners.

Error Handling

Evidence-Driven Salesforce Performance Tuning

Overview

Optimize the end-to-end workload without trading correctness, permission enforcement, shared capacity, or recovery for a synthetic benchmark.

Prerequisites

• Representative workload, latency and throughput objectives, business invariant, and current telemetry
• Queries, object volumes, selectivity, pagination, automation, locks, API mode, limits, and downstream timing
• Authorized performance org or sandbox, synthetic dataset, stop thresholds, and rollback owner

Tool Discipline

Use Read, Glob, and Grep to inspect approved repository and evidence files, WebFetch to re-check current first-party Salesforce documentation, and Write or Edit only for secretless plans, fixtures, configuration, and redacted receipts.

Current Contract

Salesforce offers versioned query and limits resources; query performance feedback through REST explain is explicitly Beta. Query plans, indexes, object cardinality, automation cost, and limits depend on the target org and must be measured.

Authentication

Use an approved read-only performance principal first and a separately approved principal for canary writes. Do not collect broad record payloads or use administrator access to mask real permission cost.

Instructions

1. Define the business invariant and measure end-to-end latency, throughput, error rate, API consumption, locks, retries, and downstream lag.
2. Trace time across client, network, authentication, query, pagination, automation, async jobs, event delivery, and reconciliation.
3. Inspect query shape, selected fields, predicates, cardinality, selectivity, ordering, pagination, and current metadata.
4. Use documented explain or query-plan tooling only under its current status and corroborate recommendations with measured tests.
5. Compare bounded changes to query design, caching, conditional requests, composite or bulk modes, concurrency, and scheduling.
6. Canary one change at a time with synthetic or approved non-production data and fixed stop thresholds.
7. Verify correctness, permissions, limits, event and business outcomes; roll back regressions and publish the evidence.

Approval Boundaries

Do not request indexes, change automation, increase concurrency, add caches, alter consistency, or load production for a benchmark without owners.

Output

Return the baseline trace, bottleneck evidence, tested alternatives, capacity effect, correctness checks, canary result, rollback, and recommendation.

Error Handling

Salesforce Integration Policy Guardrails

Overview

Turn recurring integration hazards into deterministic checks with fail-closed severity, exact evidence, owned exceptions, and no secret-dependent fork execution.

Prerequisites

• Repository, Salesforce DX or adapter layout, languages, CI trust model, protected branches, and code owners
• Current API EOL, OAuth, security, object and field access, sharing, limits, and deployment contracts
• Policy authority, severity model, baseline findings, exception format, expiry, and remediation owners

Tool Discipline

Use Read, Glob, and Grep to inspect approved repository and evidence files, WebFetch to re-check current first-party Salesforce documentation, and Write or Edit only for secretless plans, fixtures, configuration, and redacted receipts.

Current Contract

Salesforce requires parameter-safe query construction and layered authorization, while supported API versions and client-app guidance evolve. Static rules cannot prove runtime CRUD, field access, sharing, limits, or org identity and must be paired with protected tests.

Authentication

Static and fixture gates must run without Salesforce credentials. Protected runtime checks use a minimum non-production principal only after exact-head trust and must never expose secrets to fork code.

Instructions

1. Inventory query construction, credentials, app and OAuth settings, API versions, objects and fields, mutations, events, retries, logs, and deployment paths.
2. Define checks for string-built SOQL, secrets, unsafe logs, retired or fixed versions, broad scopes, wrong-org defaults, and unrestricted queries.
3. Add rules for missing CRUD and field-access evidence, destructive operations, blind retries, unbounded concurrency, checkpoint resets, and reconciliation gaps.
4. Create positive and negative fixtures for every rule and pin scanners, actions, runtimes, dependencies, and rule hashes.
5. Run secretless checks on every change and protected org contract checks only in trusted environments.
6. Ratchet against a reviewed baseline; require exact finding, owner, reason, scope, expiry, and compensating control for exceptions.
7. Measure escapes and false positives, close expired waivers, and update policies from incidents and Salesforce contract changes.

Approval Boundaries

Do not suppress blockers, broaden globs, add permanent waivers, expose CI secrets, or auto-fix Salesforce org state without policy-owner approval.

Output

Return the policy catalog, authority and hashes, fixture results, findings, baseline delta, exceptions with expiry, protected-test receipt, and owners.

Error Handling

Salesforce Production Readiness Gate

Overview

Convert a release candidate into an evidence-backed go or no-go decision with named owners, bounded execution, and tested recovery.

Prerequisites

• Immutable release candidate, change record, production org, maintenance window, and business owner
• Validated metadata and integration dependencies, API versions, permissions, limits, data mappings, and test evidence
• Canary, reconciliation, rollback or compensating action, communications, and Salesforce Support plans

Tool Discipline

Use Read, Glob, and Grep to inspect approved repository and evidence files, WebFetch to re-check current first-party Salesforce documentation, and Write or Edit only for secretless plans, fixtures, configuration, and redacted receipts.

Current Contract

Salesforce release behavior depends on org metadata, automation, permissions, seasonal version, API support, entitlements, and shared capacity. Validation in a lower org reduces risk but does not prove production parity.

Authentication

Use separate named non-production and production authorization with minimum deployment and verification permissions. Production credentials must be protected, short-lived where supported, auditable, and unavailable to fork-origin code.

Instructions

1. Freeze the candidate SHA, metadata manifest, adapter artifact, dependency lock, API contract, and generated outputs.
2. Compare production and validation orgs for edition, features, packages, schema, permissions, sharing, automation, limits, and data assumptions.
3. Review security, privacy, segregation-of-duties, destructive-change, backfill, event, and support impacts.
4. Run static checks, unit tests, Apex or Flow tests, deployment validation, contract tests, and synthetic integration checks.
5. Approve a small canary with explicit users, objects, records, time box, stop signals, and rollback owner.
6. Execute only in the window, preserve deployment and request IDs, and monitor platform, application, limit, event, and business signals.
7. Reconcile metadata and data invariants, decide promote or rollback, communicate outcome, and retain the evidence bundle.

Approval Boundaries

Do not approve, deploy, activate, mutate, backfill, or disable controls without release, Salesforce admin, security, data, and business-owner authorization.

Output

Return a signed readiness matrix, parity gaps, gate results, canary scope, stop signals, deployment receipt, reconciliation, rollback state, and follow-up owners.

Error Handling

Salesforce Org Limit and Capacity Governance

Overview

Treat limits as shared, time-varying org contracts and allocate headroom across integrations without publishing fixed universal thresholds.

Prerequisites

• Authorized org, workload, API and event modes, business priority, and peer integrations
• Current Limits resource, Sforce-Limit-Info, job, event-usage, and application telemetry
• Platform, integration, incident, and business owners with a deferral policy

Tool Discipline

Use Read, Glob, and Grep to inspect approved repository and evidence files, WebFetch to re-check current first-party Salesforce documentation, and Write or Edit only for secretless plans, fixtures, configuration, and redacted receipts.

Current Contract

The versioned Limits REST resource returns maximum and remaining allocations and can lag consumption by up to five minutes. Sforce-Limit-Info reports REST API usage; names, allocations, windows, grace behavior, and entitlements vary by org, edition, license, API version, and workload.

Authentication

Use an approved read-only principal with the permission required to view limits. Do not expose tokens, org identifiers, or unrelated allocation details in public metrics or receipts.

Instructions

1. Inventory every workload sharing the org, its API mode, priority, schedule, concurrency, retry behavior, and owner.
2. Discover a supported API version and capture current Limits and response-header evidence with timestamps.
3. Map relevant REST, bulk, async, Apex, storage, and event allocations to workloads and business deadlines.
4. Model normal, burst, retry-storm, backfill, and incident demand with an explicit measurement-lag safety margin.
5. Define admission, concurrency, batching, backpressure, deferral, and stop policies per priority class.
6. Test the policy with synthetic work in an authorized non-production org and prove hard exhaustion is not blindly retried.
7. Monitor actual usage and reconcile deferred work; review allocations and policy after releases, license changes, and incidents.

Approval Boundaries

Do not consume production capacity for testing, raise concurrency, defer critical work, purchase capacity, or disable peer integrations without accountable owners.

Output

Return the dated allocation snapshot, workload budget, scenarios, safety margin, controls, alerts, deferred-work ledger, and review owner.

Error Handling

Governed Salesforce Integration Reference Architecture

Overview

Create an evidence-backed target architecture that names every source of truth, mutation path, principal, data class, failure boundary, and recovery mechanism.

Prerequisites

• Business capabilities, system context, sources of truth, data owners, consumers, service objectives, and constraints
• Org topology, Salesforce products, External Client Apps or existing Connected Apps, APIs, events, limits, and entitlements
• Security, privacy, residency, retention, reconciliation, disaster recovery, support, and change-control requirements

Tool Discipline

Use Read, Glob, and Grep to inspect approved repository and evidence files, WebFetch to re-check current first-party Salesforce documentation, and Write or Edit only for secretless plans, fixtures, configuration, and redacted receipts.

Current Contract

Salesforce provides multiple synchronous, asynchronous, bulk, composite, and event integration surfaces with org-specific availability and limits. No single direct API, middleware, replicated database, or event pattern is correct for every domain.

Authentication

Model human, integration, deployment, diagnostic, and break-glass principals separately. Bind each to an approved app, OAuth flow, minimum permissions, secret custody, rotation, revocation, and audit path.

Instructions

1. Map systems, trust zones, sources of truth, record and event ownership, consumers, data classes, and business invariants.
2. Inventory orgs, products, editions, packages, schemas, API versions, events, limits, identities, and operational dependencies.
3. Select interaction patterns per use case: synchronous request, asynchronous bulk, composite, event, scheduled reconciliation, or replicated read model.
4. Define contracts for schema, versioning, idempotency, ordering, pagination, checkpoints, retries, dead letters, and backfills.
5. Design CRUD and field access, sharing, encryption, retention, audit, residency, redaction, support, and separation of duties.
6. Model outages, limit exhaustion, partial writes, event gaps, schema drift, wrong-org access, and disaster recovery.
7. Validate with threat, failure, capacity, cost, operability, migration, and rollback reviews and record rejected alternatives.

Approval Boundaries

Do not establish new trust, data movement, system authority, production mutation, or vendor dependency without architecture, security, data, and business approval.

Output

Return context and container views, authority matrix, trust and data-flow boundaries, contracts, failure scenarios, capacity and cost assumptions, decisions, risks, and migration plan.

Error Handling

Salesforce Reliability and Recovery Patterns

Overview

Make every read, write, job, and event path safe under duplicate, delayed, partial, uncertain, throttled, and unavailable outcomes.

Prerequisites

• Business invariants, sources of truth, operation classes, stable keys, ordering, latency, and recovery objectives
• Current Salesforce API, event, limit, error, job-result, and transaction contracts
• Durable queue and checkpoint stores, quarantine or dead-letter path, reconciliation, backfill, and owners

Tool Discipline

Use Read, Glob, and Grep to inspect approved repository and evidence files, WebFetch to re-check current first-party Salesforce documentation, and Write or Edit only for secretless plans, fixtures, configuration, and redacted receipts.

Current Contract

Salesforce synchronous, composite, bulk, and event surfaces have different transaction, result, retry, ordering, and recovery semantics. CDC can emit gap or overflow events; no transport removes the need for idempotency and reconciliation.

Authentication

Use separate minimum-permission principals for runtime, repair, and diagnostics. Protect tokens, payloads, checkpoints, dead letters, and repair tooling from unauthorized access and logging.

Instructions

1. Classify each operation as read, create, update, upsert, delete, job, publish, or consume and define its invariant and stable key.
2. Document timeout, error, partial-result, transaction, limit, ordering, duplicate, replay, and retention semantics from current contracts.
3. Design idempotency through external IDs, request ledgers, deduplication keys, conditional state, or invariant checks appropriate to the operation.
4. Retry only classified transient failures with bounded attempts, jitter, budget, and circuit breaking; reconcile uncertain outcomes first.
5. Persist queue, job, checkpoint, schema, and dead-letter state durably with redaction, retention, and ownership.
6. Test token expiry, timeouts, partial writes, locks, hard limits, duplicate events, gaps, schema drift, consumer outage, and restart.
7. Run recovery and backfill drills, compare against the source of truth, and measure recovery objectives and duplicate business effects.

Approval Boundaries

Do not replay, purge queues, skip failed records, alter checkpoints, repair data, fail over, or change retry budgets without application and data owners.

Output

Return the operation contracts, failure matrix, idempotency and retry design, durable-state schema, test results, recovery receipt, gaps, and owners.

Error Handling

Salesforce Typed Adapter and Client-Library Boundary

Overview

Contain library churn and org-specific schema behind a small adapter whose types, API version, permissions, retries, and evidence are explicit.

Prerequisites

• Repository, runtime, supported environments, and selected Salesforce library or CLI
• Current dependency lock, org schema evidence, API support policy, and error samples
• Application, Salesforce platform, security, and data owners

Tool Discipline

Use Read, Glob, and Grep to inspect approved repository and evidence files, WebFetch to re-check current first-party Salesforce documentation, and Write or Edit only for secretless plans, fixtures, configuration, and redacted receipts.

Current Contract

Salesforce publishes versioned API contracts, while third-party client libraries have independent release and support policies. Object and field shapes remain customer-specific, so generated or handwritten types must be tied to dated metadata evidence.

Authentication

Accept an authenticated client or secret reference from the approved authorization layer. The adapter must not invent a password fallback, persist tokens, broaden scopes, or choose a production org implicitly.

Instructions

1. Inventory direct Salesforce calls, library versions, API versions, objects, fields, mutations, retries, and error handling.
2. Define a narrow adapter interface for identity, metadata discovery, reads, bounded writes, async jobs, and limits.
3. Bind types to dated object metadata or a governed schema snapshot and label nullable, encrypted, formula, and inaccessible fields.
4. Centralize pagination, request IDs, timeouts, idempotency keys or external IDs, error normalization, and redaction.
5. Add contract fixtures for success, partial failure, token expiry, permission denial, schema drift, limits, and timeouts.
6. Test the adapter without a live org, then run approved read-only and sandbox mutation probes.
7. Migrate callers incrementally and retain a reversible compatibility boundary until evidence is complete.

Approval Boundaries

Do not upgrade dependencies, change API versions, regenerate broad schemas, or perform live writes without code owner, platform owner, and data owner approval.

Output

Return the adapter contract, dependency and API matrix, schema provenance, fixture coverage, migration plan, live probe receipt, and rollback boundary.

Error Handling

Salesforce Integration Security Baseline

Overview

Build a shared-responsibility control set that connects the external application, Salesforce org, principal, data, event, and operational boundaries.

Prerequisites

• System context, data classes, org topology, app type, principal, APIs, events, and support paths
• Current customer security policy, Salesforce security documentation, and threat model
• Identity, security, Salesforce administration, privacy, data, application, and incident owners

Tool Discipline

Use Read, Glob, and Grep to inspect approved repository and evidence files, WebFetch to re-check current first-party Salesforce documentation, and Write or Edit only for secretless plans, fixtures, configuration, and redacted receipts.

Current Contract

Salesforce access combines OAuth client policy, user or integration-principal permissions, object CRUD, field-level access, record sharing, org settings, and optional security products. Controls and entitlements must be verified in the target org.

Authentication

Prefer an External Client App for new REST integrations where the org contract requires it, or govern an approved existing Connected App. Use workload-appropriate OAuth, minimum scopes, protected secret custody, rotation, revocation, and no human-password automation.

Instructions

1. Map trust boundaries, principals, orgs, APIs, events, data classes, mutations, logs, vendors, and failure paths.
2. Verify app type, OAuth flow, scopes, policies, certificate or secret custody, token lifetime, rotation, and revocation.
3. Review permission sets or groups, profile baseline, CRUD, field access, sharing, elevated access, and separation of duties.
4. Inspect queries, payloads, caches, queues, logs, exports, support bundles, backups, and retention for minimum-data handling.
5. Assess SOQL injection, mass assignment, replay, duplicate mutation, confused-deputy, mixed-org, and secret-exposure threats.
6. Test denied paths, expired and revoked credentials, inaccessible fields, sharing restrictions, redaction, and break-glass audit.
7. Track every gap with severity, owner, deadline, compensating control, verification evidence, and review cadence.

Approval Boundaries

Do not change app policy, scopes, permissions, sharing, encryption, retention, or monitoring without security, admin, privacy, and data-owner approval.

Output

Return the threat model, access matrix, control evidence, denied-path tests, gaps, compensating controls, rotation and revocation proof, and owners.

Error Handling

Salesforce API and Toolchain Upgrade Control

Overview

Replace fixed-version guesswork with a complete inventory, compatibility matrix, staged validation, explicit ownership, and reversible consumer migration.

Prerequisites

• Repository and org inventory with API versions, libraries, CLI, metadata, events, packages, and consumers
• Current Salesforce API EOL policy, seasonal release notes, dependency releases, and customer support constraints
• Test environments, representative fixtures, compatibility owner, migration window, and rollback point

Tool Discipline

Use Read, Glob, and Grep to inspect approved repository and evidence files, WebFetch to re-check current first-party Salesforce documentation, and Write or Edit only for secretless plans, fixtures, configuration, and redacted receipts.

Current Contract

Salesforce supports REST API versions for a documented lifecycle and retires older versions after notice. As of this review, versions 21.0 through 30.0 are unavailable, while the current support table must be re-fetched before every migration.

Authentication

Use existing approved app and principal contracts for compatibility tests. Do not add a password fallback, copy production tokens into test, or broaden access to compensate for an upgrade defect.

Instructions

1. Inventory every explicit and library-default API version, CLI and library version, endpoint, schema snapshot, event client, and metadata consumer.
2. Re-fetch the API EOL table, release notes, client-library releases, CLI contract, and org upgrade schedule.
3. Classify each dependency as supported, deprecated, retired, preview, beta, or customer-specific and name an owner.
4. Build fixtures for response, error, pagination, metadata, event schema, limits, and partial-failure compatibility.
5. Upgrade one boundary at a time in a branch and validate static, unit, contract, sandbox, and deployment checks.
6. Canary representative reads and approved non-production writes, then migrate consumers in reversible cohorts.
7. Reconcile results, remove old versions only after all consumers and rollback windows close, and schedule the next review.

Approval Boundaries

Do not change API versions, dependencies, org settings, metadata, event consumers, or production traffic without code, platform, security, and business-owner approval.

Output

Return the version inventory, authority evidence, compatibility matrix, changed contracts, test results, cohort plan, rollback point, and retirement date.

Error Handling

Salesforce Event and Change-Delivery Decision

Overview

Choose the supported delivery contract from business semantics, entitlement, transport, ordering, replay, schema, security, and recovery evidence.

Prerequisites

• Business event or record-change definition, producer, consumers, latency, ordering, volume, and recovery objective
• Current org edition, event entitlements, permissions, channels, schema, delivery allocation, and support contract
• Consumer idempotency, checkpoint or replay state, dead-letter path, reconciliation, and backfill owner

Tool Discipline

Use Read, Glob, and Grep to inspect approved repository and evidence files, WebFetch to re-check current first-party Salesforce documentation, and Write or Edit only for secretless plans, fixtures, configuration, and redacted receipts.

Current Contract

Pub/Sub API uses gRPC over HTTP/2 and Avro for platform events, Change Data Capture, and real-time event monitoring. CDC publishes near-real-time record changes and can emit gap or overflow events; other Salesforce delivery mechanisms have different contracts.

Authentication

Use the documented OAuth and permission model for the selected producer and consumer. Protect tokens, event payloads, replay or checkpoint state, schemas, org identifiers, and personal data.

Instructions

1. Define business semantics, source of truth, producer authority, consumers, payload minimum, ordering key, latency, and loss tolerance.
2. Discover the org edition, enabled event products, Pub/Sub or alternative availability, channels, permissions, schemas, and allocations.
3. Compare Pub/Sub API, CDC, custom Platform Events, event relay, Streaming API, Outbound Messages, and bounded polling against requirements.
4. Design idempotency, schema compatibility, checkpoint or replay handling, flow control, reconnect, dead letter, and poison-event isolation.
5. Model duplicate, delayed, out-of-order, gap, overflow, schema-change, permission-loss, quota, and consumer-outage cases.
6. Run a synthetic non-production publication or change canary and prove delivery, recovery, redaction, and no duplicate business effect.
7. Enable production in a bounded cohort, monitor delivery and business reconciliation, and maintain a documented backfill path.

Approval Boundaries

Do not enable entities, create channels, publish events, expose fields, reset checkpoints, replay, or backfill without platform, data, security, and consumer-owner approval.

Output

Return the delivery decision, entitlement evidence, schema and permission contract, capacity plan, recovery design, canary receipt, reconciliation, and owners.

Error Handling