Home / admin / requirements-gathering-for-sf

requirements-gathering-for-sf

Eliciting, documenting and structuring requirements for a Salesforce implementation: stakeholder discovery interviews, As-Is and To-Be process mapping, and gap analysis against standard Salesforce capability.

• v1.1.0
• Salesforce Spring '25+
• Updated 2026-09-04
• Operational Excellence
• User Experience

• requirements-gathering
• business-analysis
• elicitation
• requirements-catalogue
• non-functional-requirements
• process-mapping
• gap-analysis

Open the skill folder on GitHub

Requirements Gathering for Salesforce

This skill activates when a Business Analyst (BA) or admin needs to elicit, structure, and document requirements before building in Salesforce. It owns elicitation and the requirements catalogue: discovery interviews, As-Is / To-Be discovery, Salesforce-specific non-functional requirements, and the catalogue rows that feed story writing, fit-gap and the configuration workbook.

The downstream artefacts are owned elsewhere and are cited, not duplicated: story shape by admin/user-story-writing-for-salesforce, Given/When/Then criteria by admin/acceptance-criteria-given-when-then, the org-scored classification by admin/fit-gap-analysis-against-org, the swim-lane diagram by admin/process-flow-as-is-to-be, the traceability grid by admin/requirements-traceability-matrix, and the 10-section handoff by admin/configuration-workbook-authoring.

Before Starting

Gather this context before conducting discovery:

• What is the trigger for this project? Understand whether it is a greenfield implementation, an enhancement to an existing org, a migration from a legacy system, or a post-release fix. Each context changes what questions to ask and which stakeholders to prioritize.
• Who are the actual end users? Salesforce has distinct personas: sales reps, service agents, managers, data stewards, and admins. Requirements differ sharply by persona. Avoid gathering requirements only from managers — the people who will use the system daily have different needs than those who sponsor it.
• What constraints exist? Platform limits (objects, fields, automation), licensing tier, existing technical debt, and integration dependencies all bound what is buildable. Establish these early to avoid promising what cannot be delivered declaratively.
• Who decides? A requirement with no named decision-maker cannot be closed. admin/stakeholder-raci-for-sf-projects owns the authority map; this skill consumes it to fill the source_stakeholder column and to route conflicts.

Questions to Ask Before Configuring

Ask these in the interview, before any story, workbook row or Setup change exists. Each one exists because skipping it produces a specific, documented failure — the gotcha number is named.

What a proper requirements catalogue adds over a list of bullet points: every row carries the five Salesforce facts (object, automation tier, sharing layer, volume, licence) that a downstream agent needs to act without re-interviewing the stakeholder, and every row has exactly one downstream target so nothing is silently dropped between discovery and build.

Core Concepts

The Requirements Catalogue — One Row Per Requirement

The catalogue is this skill's primary artefact. It is a flat, machine-lintable list — not prose — because every downstream consumer reads rows, not paragraphs.

A filled catalogue, an NFR sheet and the handoff map are in references/worked-examples.md. Lint any catalogue with scripts/check_requirements_catalogue.py.

Capture candidates, not decisions. objects and automation_candidate are hypotheses the BA records so the downstream agent has a starting point and a reason to disagree. The BA does not own the Flow-vs-Apex call — the tree and the builder agent do. What the BA owns is that the row names a tree step at all, so the decision is visible rather than assumed.

Salesforce Non-Functional Requirements

Generic NFR checklists (performance, availability, security) do not survive contact with a multitenant platform. Six NFR classes matter on a Salesforce project, and each is bounded by a specific platform fact that must be written next to the requirement:

Storage is deliberately absent from that table: the Developer Limits quick reference states up front that it does not cover contractual limits, so data and file storage allocations must be read from the org's own Storage Usage page rather than quoted from a guide.

Mobile and offline capture belongs in the interview — which steps happen away from a desk, and whether the user can be assumed online — but the capability that satisfies it is org-specific. UNVERIFIED (2026-09-04): no offline-entry limit or allocation appears in the eight extracted Salesforce guides used to ground this skill; confirm the org's mobile configuration before promising offline data entry.

Salesforce-Specific User Story Format

Generic agile user stories ("As a user, I want X so that Y") are insufficient for Salesforce because they do not capture the platform-specific decisions required before building. A Salesforce user story must answer:

1. Who — which Salesforce profile, permission set, or role
2. What object — which standard or custom object is involved
3. What fields — which fields need to be visible, editable, or required
4. What automation — what should happen automatically (Flow, validation rule, approval)
5. What sharing — who else needs to see or edit this record

A complete Salesforce user story format:

As a [persona with Salesforce role/profile context],
I want [feature involving specific Salesforce object/field/automation],
So that [business outcome].

Acceptance Criteria:
- [ ] If on [page/screen], then [specific Salesforce field/button] is visible and editable for [profile/permission set]
- [ ] If [condition], then [validation rule or automation] fires with error message "[text]"
- [ ] If [user with role], then record is accessible under [sharing rule or OWD setting]
- [ ] If [filter criteria], then [report or list view] returns records with [specific fields]

Salesforce Trailhead specifies the if/then format for acceptance criteria: each criterion takes the form "If [condition], then [observable Salesforce outcome]." This format ensures every criterion is independently testable with a boolean pass/fail result — suitable for UAT without interpretation. A story is an invitation to a conversation, not a contract; do not over-specify which Flow type or which Apex class will implement it.

INVEST quality check: Every Salesforce user story should meet the INVEST criteria — Independent (not blocked by another incomplete story), Negotiable (implementation detail is flexible), Valuable (delivers a business outcome), Estimable (the build team can size it), Small (fits in a sprint), Testable (acceptance criteria are boolean pass/fail). Stories that fail INVEST — especially "not independent" due to platform dependencies like page layout depending on record type completion — should be split or reordered in the backlog.

This format forces discovery of FLS, page layout, and sharing requirements at the story level — not as a surprise during UAT. The story shape and the splitting techniques belong to admin/user-story-writing-for-salesforce; what this skill owns is that the catalogue row feeding the story already carries the object, automation, sharing and volume facts.

As-Is / To-Be Process Mapping

As-Is mapping documents how the business currently operates — often in spreadsheets, email, or a legacy CRM. It is essential to capture:

• Who does what, in what order
• Where handoffs between teams occur
• Where data is duplicated or lost
• Where manual steps are error-prone

To-Be mapping documents how the same process will operate in Salesforce. Each step of the To-Be process should reference a specific Salesforce feature: a screen flow, a record-triggered flow, an approval process, a queue, a report, or a dashboard.

Mapping notation: Salesforce Trailhead recommends Universal Process Notation (UPN) as the preferred notation for BA process maps. UPN answers "Who needs to do what, when, why, and how?" in a single readable diagram. Each activity box uses a verb phrase and contains a named resource (the who). Lines between boxes represent handoffs with explanatory text. Limit each diagram to 8–10 activity boxes; drill down to child diagrams for complex sub-processes. UPN is preferred over BPMN because it has fewer symbols and is readable left-to-right without specialized training.

Where the diagram lives: this skill produces the As-Is / To-Be summary table — one row per step, with the pain point, the Salesforce feature and the catalogue row it generated. The swim-lane diagram itself, its lane rules, decision diamonds, sad paths and automation-tier annotations belong to admin/process-flow-as-is-to-be and agents/process-flow-mapper. Hand the summary table over; do not draw the lanes here.

Transition state: The official Salesforce BA methodology requires three states, not two: As-Is (current), To-Be (target end state), and Transition State (how the org and team will operate during the migration from As-Is to To-Be). Omitting the transition state is a common gap in requirements packages that causes go-live disruption when the old process ends before the new one is stable.

Fit-Gap Analysis

A fit-gap analysis compares each business requirement against what standard Salesforce delivers. Classification:

Identifying process gaps early is the most valuable BA output. A requirement that cannot be met with any Salesforce feature needs to be renegotiated with the business, not coded around.

This four-way split is the BA's pre-org read, made from the requirement alone. The five-tier scoring against an actual org — with effort tier, risk tag and AppExchange suggestion — is admin/fit-gap-analysis-against-org and agents/fit-gap-analyzer, which refuse to run without a target org alias. Feed them catalogue rows; do not pre-empt their tiers.

Common Patterns

Pattern: Discovery Interview for a New Salesforce Feature

When to use: When starting a new user story or feature with a stakeholder who has never used Salesforce before, or when requirements are vague.

How it works:

1. Current state questions: "Walk me through exactly what you do today when [business event occurs]. What system do you use? What data do you enter? Who else is involved?"
2. Pain point questions: "Where does this process break down? What takes the most time? What data do you wish you had but don't?"
3. Future state questions: "If this worked perfectly, what would the process look like? What would you see on your screen? What would happen automatically?"
4. Volume and frequency questions: "How many records are created per day/week/month? How many people do this? What is the peak load?"
5. Exception questions: "What are the edge cases? What should NOT happen automatically? Who handles exceptions?"
6. Map each answer to a Salesforce concept: object, field, automation, sharing rule, report.

Why not to skip volume questions: Volume determines whether a declarative solution (Flow) is safe or whether Apex/Bulk API is required. 10,000 records per day triggers governor limit conversations that a BA must surface early.

Pattern: The Solution-to-Requirement Rewind

When to use: When the stakeholder has arrived with a solution — "build a trigger", "we need a custom object for this", "just add a checkbox" — instead of a requirement.

How it works:

1. Write the sentence down verbatim in the interview notes; do not correct it in the room.
2. Ask "what happens today if that doesn't exist?" and "what would you see that tells you it worked?" The answers are the requirement.
3. Restate the requirement as an outcome and get the stakeholder to confirm it: the catalogue statement is the confirmed sentence, not the original.
4. Move the original solution into automation_candidate as a hypothesis, and walk standards/decision-trees/automation-selection.md from Q1 to record the step that actually resolves it.
5. If the tree lands somewhere other than the stakeholder's solution, record both in the row's notes. That difference is the conversation to have at design review, not at UAT.

Pattern: Fit-Gap Workshop

When to use: When a list of requirements exists and the team needs to classify which are standard, which need configuration, and which need custom code — before sprint planning.

How it works:

1. List all requirements as rows in a table (one per user story or business rule).
2. For each requirement, check Salesforce Help and Trailhead for the standard feature that addresses it.
3. Classify each requirement: Standard Fit / Configuration Gap / Customization Gap / Process Gap.
4. For Customization Gaps, note the AppExchange options before defaulting to custom development.
5. Summarize by type: # standard, # config, # custom, # process. This becomes the basis for sizing.
6. Flag any requirement that cannot be met with standard Salesforce as a stakeholder decision — do not let these requirements silently become custom code.

Decision Guidance

Recommended Workflow

1. Frame the scope and the deciders. Name the process, the clouds in scope, and — from admin/stakeholder-raci-for-sf-projects — the one accountable owner per decision area. Open templates/requirements-gathering-for-sf-template.md and fill the Project Context block. A scope with no named decider produces rows that can never leave status: draft.
2. Run the interviews from the seven questions. Work the ## Questions to Ask Before Configuring table with each persona separately — end users first, managers second. Record answers verbatim; do not translate to Salesforce terms in the room. The interview guide in references/worked-examples.md shows the Salesforce-aware probe under each question.
3. Write the As-Is / To-Be summary table, including the transition state. One row per step: actor, what happens today, the pain point, the To-Be Salesforce feature, and the REQ- ids that step generated. Hand the table to admin/process-flow-as-is-to-be for the swim-lane diagram rather than drawing lanes here.
4. Build the catalogue. One row per requirement in the shape above. For every row that names a mechanism, walk standards/decision-trees/automation-selection.md or sharing-selection.md and record the step id. For every external-data row, record the integration-pattern-selection branch. Copy the YAML skeleton from templates/requirements-catalogue.yaml.
5. Fill the NFR sheet. For each of the six NFR classes, write the requirement and the bounding platform fact beside it. Any row without a number is not yet an NFR — go back to the stakeholder.
6. Lint. Run python3 scripts/check_requirements_catalogue.py --file requirements-catalogue.yaml (or --manifest-dir docs/discovery/). It fails on missing required fields, duplicate ids, non-MoSCoW priorities, rows with no stakeholder, rows with no downstream target, automation rows with no decision-tree step, sharing rows that name no layer, and NFR rows with no measure. Fix every ERROR before handing off.
7. Publish the handoff map and hand over. Map each catalogue row to exactly one of agents/story-drafter, agents/fit-gap-analyzer, agents/process-flow-mapper or agents/config-workbook-author, then check the ## Review Checklist below. A row with no target is a dropped requirement, not a finished one.

Review Checklist

Run through these before handing requirements to the build team:

• [ ] Every catalogue row has an id, a statement in outcome language, a named source_stakeholder, a MoSCoW priority, a status, and at least one downstream target
• [ ] Every row that names an automation mechanism cites the automation-selection step that produced it
• [ ] Every visibility requirement names one of the seven sharing layers, and field-level requirements are recorded as separate rows from record-level ones
• [ ] Every automation requirement carries a steady-state volume and a worst-case batch number
• [ ] Every external-data requirement names direction, latency tolerance and an integration-pattern-selection branch
• [ ] Every reporting requirement names its base object and join chain, checked against the four-object ceiling
• [ ] Every row involving a non-employee user carries a licence_implication
• [ ] python3 scripts/check_requirements_catalogue.py reports zero ERRORs
• [ ] As-Is process has been reviewed with at least one actual end user (not just a manager)
• [ ] To-Be process maps each step to a specific Salesforce feature (not just "Salesforce does it"), and a transition state exists
• [ ] Fit-gap pre-read is complete: every requirement classified as Standard, Configuration, Customization, or Process gap, with Customization Gaps checked for AppExchange alternatives and Process Gaps escalated to a business owner
• [ ] Every "as today" requirement has been challenged: is this a business rule or a legacy workaround?

Salesforce-Specific Gotchas

Non-obvious platform behaviors that cause real production problems:

1. Requirements written for the wrong persona — BAs often interview managers, not end users. Managers describe what they want to see in reports. Sales reps describe what they want to see on a record page. Both are valid but produce entirely different requirements. If stories are written from the manager's perspective only, the resulting build frustrates end users and drives low adoption.
2. "Make it automatic" requirements that hide complexity — Stakeholders often request "it should just happen automatically" without understanding the trigger, the conditions, or the exception path. Before accepting any automation requirement, a BA must capture: the exact record trigger (created, updated, deleted), the field condition, what happens to exceptions, and who is notified when the automation fails. Undiscovered exception paths surface in UAT as blocking defects.
3. Process gaps misclassified as configuration work — Occasionally a business requirement has no Salesforce equivalent and no configuration workaround. For example, "the system should prevent a rep from creating an Opportunity if the Account credit limit is exceeded" sounds like a validation rule, but credit limits live in an ERP, not Salesforce. Without the integration requirement being surfaced as a gap, an admin may build a placeholder validation rule with hardcoded values — creating technical debt and the wrong behavior. Always ask "where does this data live?" before classifying a requirement.

The full set, with what happens / when it occurs / how to avoid, is in references/gotchas.md.

Output Artifacts

Reference Files

Related Skills

• admin/user-story-writing-for-salesforce: Use once catalogue rows are confirmed and each must become an INVEST story with a stem, size and handoff metadata. NOT for elicitation.
• admin/acceptance-criteria-given-when-then: Use to convert a story into Given/When/Then criteria with permission and data-state preconditions. NOT for capturing the requirement itself.
• admin/fit-gap-analysis-against-org: Use to score the catalogue against a real org — five-tier classification, effort tier, risk tag, AppExchange suggestion. It refuses without a target org alias.
• admin/process-flow-as-is-to-be: Use to turn the As-Is/To-Be summary table into swim lanes with decision diamonds, sad paths and automation-tier annotations.
• admin/requirements-traceability-matrix: Use to carry REQ- ids forward to story, test and defect ids for audit and steering-committee reporting.
• admin/configuration-workbook-authoring: Use to compile confirmed rows into the 10-section admin handoff workbook — the last document before Setup changes begin.
• admin/stakeholder-raci-for-sf-projects: Use to establish who is accountable for each decision area before interviews start; supplies the escalation path for conflicting requirements.
• admin/moscow-prioritization-for-sf-backlog: Use when the priority column needs to become a release-capacity decision rather than a label.
• admin/portal-requirements-gathering: Use when the answer to "who does this" is a customer or partner and the requirement implies an Experience Cloud site.
• admin/report-type-strategy: Use when a reporting requirement's join chain has to be proved legal before it is promised.
• admin/process-automation-selection: Use to walk the automation tier decision for a specific requirement row.
• architect/license-optimization-strategy: Use when licence implications recorded during discovery need costing and edition/SKU selection.
• architect/large-data-volume-architecture: Use when a recorded volume figure crosses into LDV territory and needs an architecture response.
• admin/uat-and-acceptance-criteria: Use to translate confirmed acceptance criteria into structured UAT test scripts.

Package files

• references/examples.md
• references/gotchas.md
• references/llm-anti-patterns.md
• references/well-architected.md
• references/worked-examples.md
• templates/requirements-catalogue.yaml
• templates/requirements-gathering-for-sf-template.md
• scripts/check_requirements_catalogue.py