Skip to content

PranavNagrecha/AwesomeSalesforceSkills / skills/admin/acceptance-criteria-given-when-then

acceptance-criteria-given-when-then

Verified

Use this skill when writing test-first, behavior-driven acceptance criteria in Given/When/Then format for a Salesforce user story. Covers happy path, edge cases, negative paths, permission boundaries, and data-state preconditions so the AC block can drive UAT scripts and Apex test design downstream. Trigger keywords: given when then, gherkin, behavior driven AC, test first acceptance criteria, scenario outline, BDD acceptance criteria. NOT for the user-story format itself (use admin/user-story-writing-for-salesforce). NOT for UAT script writing (use admin/uat-test-case-design). NOT for Apex test method generation (use agents/test-class-generator). NOT for high-level UAT planning (use admin/uat-and-acceptance-criteria). More triggers: acceptance criteria record, ac_id, req_id on a criterion, artefact under test, negative case for a rule-type requirement, no-match fall-through criterion, oracle for a Then clause, test type apex flow manual, criteria linter, check_ac_format.py, --manifest-dir.

references/well-architected.md

View on GitHub
# Well-Architected Notes — Acceptance Criteria Given/When/Then

## Relevant Pillars

- **Reliability** — A precise, paired AC block (every "should" has a "should not", every single-record path has a bulk path) is what catches the governor-limit and async-timing defects that turn a release into an outage. AC is the upstream artifact that determines whether reliability gets tested at all.
- **User Experience** — Behavior-driven AC keeps the contract focused on what the user can observe (a field value, a record state, an error message), not on UI chrome that changes between releases. UX outcomes are tested deterministically rather than by visual inspection.
- **Operational Excellence** — Given/When/Then is the canonical input shape for downstream agents (`agents/test-class-generator`, `agents/data-loader-pre-flight`, `admin/uat-test-case-design`). When AC is in this shape, the whole test pipeline is automatable; when it is not, every handoff requires manual rework.

## Architectural Tradeoffs

- **Verbosity vs. precision** — Given/When/Then takes more lines than "the user can edit the record". The tradeoff is that it can be tested unambiguously. For a 1-line clarification fix, prefer a comment in the story; for any behavior that touches automation, sharing, or integration, the AC must be Given/When/Then.
- **Scenario Outlines vs. expanded Scenarios** — A Scenario Outline with an Examples table is denser but harder to scan. Use it when the same shape applies to 3+ data points; expand to discrete Scenarios when the shape genuinely diverges.
- **Synchronous vs. eventual Then** — A synchronous Then is easier to test but lies when the implementation is async. Always use `Then eventually within N seconds` for Queueable, Platform Event, batch, and integration-bound outcomes — even if the current implementation happens to commit synchronously.

## Anti-Patterns

1. **Compound AC with multiple Whens** — "When the user saves the record AND the manager approves AND the system sends an email." This is three Scenarios. Splitting them is what lets the team see exactly which behavior regressed.
2. **Happy-path-only AC** — Every Scenario without a paired negative-path Scenario is a half-finished AC block. Production defects almost always come from the missing deny-case, not the missing happy-case.
3. **AC that asserts implementation, not behavior** — "Given a Process Builder fires on Opportunity insert" couples the AC to the chosen automation tool. Replace with "Given an Opportunity is inserted" and let the design team pick Flow vs Apex via `standards/decision-trees/automation-selection.md`.

## Official Sources Used

Every bullet below was read while writing this skill; the parenthesis names the claim it grounds.
Line numbers are into the plain-text extractions of the Summer '26 / v62 PDFs listed in
`standards/official-salesforce-sources.md`.

- **Metadata API Developer Guide** — https://resources.docs.salesforce.com/262/latest/en-us/sfdc/pdf/api_meta.pdf — `AssignmentRules` / `AssignmentRule` (L23661–23713: rule entries are processed in container order — the ordering fact behind gotcha 10 and `worked-examples.md` AC-001.3); `AutoResponseRules` (L25196–25288: entry order selects the template, `senderEmail` / `template`, and the Classic-template packaging note behind REQ-002); `EscalationRules` (L59421–59499: container order, `businessHoursSource`, `escalationStartTime`, `disableEscalationWhenModified`, `minutesToEscalation` — REQ-003 and gotcha 12); `EntitlementProcess` (L59075–59217: versioned file naming, `minutesToComplete`, `useCriteriaStartTime`, and the negative-vs-positive `timeLength` that distinguishes a warning trigger from a violation trigger — REQ-004); `ValidationRule` (L45385–45403: `errorConditionFormula`, `errorDisplayField`, and the 255-character `errorMessage` limit — REQ-006); `PermissionSetObjectPermissions` (L95077–95113: `allowEdit` is an object-level capability while `modifyAllRecords` / `viewAllRecords` are the ones that apply "regardless of the sharing settings" — REQ-005); `CaseSettings` (L111700–111712, L112031–112033, L112133–112134: `defaultCaseOwner` as the assignment fall-through, `defaultCaseUser` as the Case History actor, and the two `caseOrigin` settings that make REQ-002's Web-vs-Email split testable); `Layout` / `FlexiPage` save options (L67423–67443, L82385–82403: whether the Case page even offers "Assign using active assignment rule" is a layout setting, which is why a manual-creation criterion has to name it).
- **Object Reference for the Salesforce Platform** — https://resources.docs.salesforce.com/262/latest/en-us/sfdc/pdf/object_reference.pdf — `BusinessHours` (L53105–53108: "Escalation rules are run only during these hours", and holidays suspend both — the fact that separates a business-hours SLA from a clock SLA); `Case` (L62470–62477 `IsEscalated`, L62575–62587 `OwnerId` refers to Group **or** User, L62659–62666 `SlaStartDate`); `CaseHistory` (L62819, L63138–63139: history exists only for **tracked** fields — gotcha 13); `CaseMilestone` (L63342–63497: `TargetDate`, `IsCompleted`, `IsViolated`, `TimeRemainingInMins`, `BusinessHoursId` — the queryable oracle for REQ-004); `EmailMessage` (L103975–103976: available only to Email-to-Case / Enhanced Email orgs — the caveat on REQ-002's convenience query); `Group` (L154213–154226 `DoesIncludeBosses`, L154307–154342 `Type`, whose values include `Queue` — what makes `Owner.Type = 'Queue'` a real assertion).
- **Apex Developer Guide** — https://resources.docs.salesforce.com/262/latest/en-us/sfdc/pdf/salesforce_apex_developer_guide.pdf — Triggers and Order of Execution (L15442, L15449–15450, L15455–15457, L15461, L15471: validation at step 5 versus assignment 9, auto-response 10, escalation 12 and entitlement 15, plus the list of rules that do not re-run after a workflow field update — gotcha 9 and the split of REQ-006 into AC-006.1 / AC-006.3); `Database.DMLOptions.assignmentRuleHeader` (L8530–8569: `useDefaultRule` / `assignmentRuleId`, and the API 30.0+ change that leaves a record unassigned rather than falling to the default owner — gotcha 11); Mixed DML in test methods (L8905–8910: `System.runAs` is what makes REQ-005 automatable).
- **Apex Reference Guide** — https://developer.salesforce.com/docs/atlas.en-us.apexref.meta/apexref/ — `DmlOptions.AssignmentRuleHeader` (L148033–148034: `useDefaultRule` "affects only the default assignment rule and does not disable other existing assignment rules on the object" — the reason an Apex criterion must name which rule it is exercising).
- **Data Loader Guide** — https://resources.docs.salesforce.com/262/latest/en-us/sfdc/pdf/salesforce_data_loader.pdf — the **Assignment rule** setting (L379–383: blank by default, and when set it "overrides Owner values in your CSV file") — one of the three disagreeing entry paths in gotcha 11 and the reason `worked-examples.md` AC-001.4 is manual.
- **Bulk API 2.0 Developer Guide** — https://resources.docs.salesforce.com/262/latest/en-us/sfdc/pdf/api_asynch.pdf — job resource `assignmentRuleId` (L1591–1595: **Optional**, so absent means no rule runs) — the second disagreeing entry path.
- **REST API Developer Guide** — https://resources.docs.salesforce.com/262/latest/en-us/sfdc/pdf/api_rest.pdf — Assignment Rule Header (L691–694: "If the header is not provided with a request, REST API defaults to using the active assignment rules") — the third, and the one that inverts the default.
- **Repo standards and sibling artefacts** — `standards/decision-trees/automation-selection.md` (cited rather than restated: the AC never names the automation tool, per gotcha 3); `admin/requirements-traceability-matrix` § ID Conventions (the `REQ-nnn` convention every criterion joins on); `admin/requirements-gathering-for-sf` § The Requirements Catalogue (the `downstream.fit_gap_row` pairing that makes `FG-XXX` and `REQ-XXX` one-to-one); `admin/configuration-workbook-authoring` § Per-Row Schema (`source_req_id`, the column the criteria feed); `admin/uat-and-acceptance-criteria/references/worked-examples.md` §§ 2.3, 3 (the persona roster and the `ac_id` column these criteria supply); `skills/admin/case-management-setup/references/worked-example-case-intake.md` (the build under test).
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 323kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 323kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 323kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall