Requirements Management: Stories, Epics, and the Gap Nobody Talks About

The Translation Gap: Why Standard Stories Fail

Agile methodologies were originally designed for custom software engineering teams starting with a clean slate. In a bespoke development environment (such as building a React frontend on a Node.js microservices backend), user stories are written in a purely functional format because the engineering team must write every single line of logic and design every database table from scratch. However, on enterprise Salesforce delivery programmes, this assumption of a blank slate is fundamentally false. Developers are working within a highly opinionated, pre-built multi-tenant CRM environment that comes with its own database schema, security sharing models, automation engines, and governor limits.

When a delivery team attempts to manage requirements using standard, generic user stories (e.g., "As a user, I want to capture preferences so that..."), they create a dangerous translation gap. The business analyst (BA) captures the customer's functional requirements in the vocabulary of the business. However, Salesforce developers speak the language of metadata (standard objects, custom objects, record-triggered flows, triggers, Apex, and permission sets). When user stories do not explicitly bridge this gap, developers are forced to make architectural and structural decisions in isolation during the sprint. A developer under time pressure will typically choose the path of least resistance—which is often to create a custom object or write a custom script—even if a standard feature or out-of-the-box configuration exists. This is the origin of the "accidental architecture" that slowly cripples enterprise Salesforce orgs.

For instance, consider a functional requirement to track customer communication preferences. A generic story might say: "As a marketing manager, I want to record custom consent channels so that we can target customers via phone, email, and SMS." If this functional story is handed directly to a developer, they might immediately create three custom checkbox fields on the Contact object. While this works in the short term, a seasoned Salesforce architect knows that this design bypasses Salesforce's native privacy objects (such as the Individual and ContactPointTypeConsent objects). By bypassing standard features, the team has introduced technical debt: they have missed out on standard multi-channel consent management features, auto-deletion logic, and standard integrations with Marketing Cloud, all of which will have to be rebuilt manually when the business scales.

To prevent this translation gap from undermining the programme, delivery leaders must shift requirements management from a functional-only model to a metadata-aware model. This requires a systematic change in how business processes are mapped, how stories are detailed, and how backlogs are refined. Requirements are not complete when the business sponsor signs off on the functional flowchart; they are only complete when that process is mapped directly to the Salesforce metadata strategy.

Conceptual to Physical: Mapping Business Objects

One of the most critical stages in Salesforce requirements management is transitioning from the business's conceptual model to the physical database structure. Business processes naturally identify entities like "subscribers," "corporate partners," "agreements," "invoices," and "support requests." The natural instinct of business analysts—and technical teams who do not understand Salesforce deeply—is to map these business entities one-to-one to custom objects in Salesforce (e.g., Partner__c, Agreement__c, Support_Request__c).

Adopting this "custom-object-first" strategy is a massive delivery failure. Standard objects in Salesforce are not simply tables in a database; they are pre-wired with deep, complex platform behaviours that are highly optimised at the database level. Bypassing these standard objects means you must recreate their native logic from scratch. For example, if you bypass the standard Lead object and build a custom Prospect__c object, you lose the native lead conversion engine. You must write custom Apex and flows to automate the creation of accounts, contacts, and opportunities, map fields across objects, and manage duplicate rules. This not only inflates development estimates but also leaves the organisation with a complex custom codebase that must be maintained through every Salesforce release.

Delivery leaders must enforce a "standard-first" architecture policy. During discovery and backlog refinement, BAs and architects must systematically map business concepts to standard objects, only utilising custom objects for unique domain extensions. The following comparison table outlines the alignment between common business entities and Salesforce standard objects, illustrating the architectural tradeoffs:

To operationalise this, delivery managers must establish a "Standard Object Audit" as part of the backlog refinement workflow. If a user story proposes a custom object, the author must explicitly document why standard objects (including standard object record types) cannot support the requirement. This single governance step can reduce the technical debt and customisation footprint of a Salesforce org by up to 30% over a multi-year programme.

Designing the Bridge: The Metadata-Aware Blueprint

To close the translation gap, user stories must become "metadata-aware." A metadata-aware user story does not merely describe the business outcome; it specifies the exact modifications required in the Salesforce metadata model. This ensures that the technical design is validated before the story is committed to a sprint, reducing sprint spillover and ensuring estimation accuracy.

A metadata-aware user story consists of six distinct, non-negotiable sections: 1. Business Context & Narrative: The standard functional description, explicitly linked to a step in a future-state business process flow diagram. 2. Metadata Impact Matrix: A detailed list of standard and custom objects, fields, page layouts, and record types that will be created or modified. 3. Declarative vs. Programmatic Strategy: A formal technical decision detailing why declarative tools (like Flow or Dynamic Forms) are being used, or why programmatic customisation (like Apex triggers or LWCs) is necessary. 4. Security & Sharing Blueprint: Definition of record-level sharing defaults (OWDs), sharing rules, field-level security (FLS), and the specific permission sets that will grant access to the new metadata. 5. Limits & Technical Boundaries: Documenting any potential governor limit considerations, API usage, high-volume data storage impacts, or potential order-of-execution conflicts with existing automation. 6. Acceptance Criteria (Gherkin format): Structured Given-When-Then scenarios that include both happy-path business logic and negative security validation.

Let us review a concrete, production-ready example of a metadata-aware user story for a GDPR-compliant customer consent tracking feature, formatted to bridge the functional-technical gap:

{
  "jira_key": "DEL-015-STORY-01",
  "epic_link": "Capability: Customer Onboarding & Verification",
  "summary": "Implement Consent Preferences on Contact",
  "functional_narrative": "As a Compliance Officer, I want to capture communication consent preferences on Contacts so that we can satisfy regional GDPR and CCPA regulations.",
  "metadata_impacts": {
    "objects": {
      "Contact": {
        "custom_fields": [
          {
            "fullName": "Consent_Status__c",
            "label": "Consent Status",
            "type": "Picklist",
            "valueSet": {
              "valueSetDefinition": {
                "sorted": false,
                "value": [
                  {"fullName": "Opt-In", "default": false, "label": "Opt-In"},
                  {"fullName": "Opt-Out", "default": true, "label": "Opt-Out"},
                  {"fullName": "Pending", "default": false, "label": "Pending Verification"}
                ]
              }
            },
            "required": true,
            "security": {
              "fieldLevelSecurity": [
                {"profile": "System Administrator", "readable": true, "editable": true},
                {"profile": "Compliance Manager", "readable": true, "editable": true},
                {"profile": "Standard Sales User", "readable": true, "editable": false}
              ]
            }
          }
        ]
      }
    },
    "automation": {
      "flows": [
        {
          "fullName": "Contact_AfterSave_Consent_Handler",
          "trigger": "Record-Triggered Flow (After Save)",
          "conditions": "IsChanged(Contact.Consent_Status__c)",
          "description": "Propagates consent status changes to the standard Individual record and issues a platform event to synchronise with Marketing Cloud."
        }
      ]
    }
  },
  "acceptance_criteria": [
    "Given a new Contact is created, the Consent_Status__c must default to 'Opt-Out' to comply with strict opt-in/opt-out legislation.",
    "When a Contact's Consent_Status__c is updated, a related Data Privacy record must be automatically updated via record-triggered flow.",
    "Verify that users without the Compliance Manager permission set cannot edit the Consent_Status__c field once it is populated."
  ]
}

By structuring stories in this manner, delivery leaders transform the backlog from a list of functional wishes into a precise engineering blueprint. Developers no longer have to guess which object schema to use or make security decisions on the fly. Furthermore, estimation becomes a science rather than an art. A story pre-mapped to custom fields, record-triggered flows, and permission sets can be accurately estimated by the development team because the architectural boundaries have already been drawn.

Structuring the Hierarchy: Epics, Features, and Stories

On large enterprise Salesforce programmes, multiple development streams (often covering different business units like sales, customer service, and digital experience) work concurrently within the same shared Salesforce org. When backlogs are structured purely around organisational departments or business lines, the programme will inevitably suffer from metadata collisions and deployment conflicts in the CI/CD pipeline.

A metadata collision occurs when two independent teams modify the same shared metadata component during a sprint. For example, if the Sales Cloud team is modifying an Account trigger to add lead scoring logic, while the Service Cloud team is modifying the same Account trigger to add entitlement routing, their changes will conflict. If their git branches are not carefully managed, one team will overwrite the other's changes, leading to regression bugs, failed deployments, and broken environments in the sandboxes.

To prevent metadata collision, delivery leaders must structure their backlogs using a capability-centric hierarchy rather than an organisational hierarchy. The backlog should be structured as follows: 1. Value Streams: The overarching business outcomes, such as "Lead-to-Cash," "Case-to-Resolution," or "Partner-Engagement." 2. Epics: Large-scale Salesforce domains and capabilities that cross organisational boundaries, such as "Account Lifecycle," "Lead Distribution," or "Service Entitlements." 3. Features: Discrete, deployable functional blocks within an Epic, such as "Geographic Lead Routing" or "SLA Escalation Alerts." 4. User Stories: Small, testable slices of business functionality that can be completed within a single sprint. 5. Platform Enablers: Technical stories that establish foundational framework architecture, such as trigger frameworks, CI/CD pipelines, or custom error logging libraries.

Platform Enablers are critical. In a professional Salesforce delivery model, technical foundations must be treated as first-class backlog items. If the team needs to build a trigger-heavy application, a Platform Enabler story must first establish a single-trigger-per-object framework (such as the ADKG framework or standard trigger handler pattern). Business user stories then build upon this pre-existing framework. By separating technical foundations from business value, delivery leaders prevent "accidental technical debt" and ensure that the platform's core architecture remains clean, scalable, and stable.

Backlog Governance: Definition of Ready and Grooming

The ultimate gatekeeper of velocity and quality in a Salesforce programme is the backlog refinement and grooming protocol. Most sprint planning sessions fail because teams attempt to estimate and commit to user stories that are functionally vague or technically incomplete. In Salesforce, estimating a story without knowing its technical approach is an invitation to sprint failure. If a story is estimated based solely on functional text, and the developer later discovers that a complex Apex trigger or integration is required to bypass a Flow limit, the story will inevitably spill over into the next sprint, disrupting the entire delivery schedule.

To establish professional backlog hygiene, delivery managers must enforce a strict, Salesforce-specific Definition of Ready (DoR). A user story is only deemed "ready" for sprint planning if it satisfies the following checklist: - Process Definition: The future-state process is documented in a visual flowchart and signed off by the business Product Owner. - Metadata Specification: All custom fields, picklists, and object relationships are defined. - Automation Plan: The declarative vs. programmatic strategy has been reviewed and approved by the Solution Architect. - Security Mapping: Field-level security (FLS) and sharing rules are explicitly documented. - Data Volume Validation: The story has been reviewed for large data volume (LDV) impacts and potential governor limit concerns. - Environment & Dependency Map: The deployment path, target sandbox, and manual post-deployment steps are identified.

This level of grooming is facilitated through a weekly Technical Grooming session. The session is led by the Delivery Manager, but the content is driven by the Business Analyst, Solution Architect, and Lead Developer. The Product Owner is present to clarify business priorities and functional intent. The Solution Architect acts as the technical gatekeeper: if a story does not have a clear metadata mapping or is architecturally unsound, the architect rejects it, and it goes back to the BA for refinement.

Holding the line on the Definition of Ready requires significant discipline, especially when stakeholders are demanding rapid progress. However, senior delivery leaders know that the cost of lazy grooming is paid with compound interest during build and testing. Enforcing a rigorous DoR ensures that sprint planning is highly efficient, developers can build without interruption, and the platform remains architecturally clean from the first sprint to go-live.