PranavNagrecha/AwesomeSalesforceSkills / skills/admin/collaborative-forecasts
collaborative-forecasts
VerifiedSet up, configure or troubleshoot Salesforce Collaborative Forecasts: forecast types, forecast categories, rollup methods, quota management, forecast hierarchy, manager adjustments, pipeline inspection integration. Trigger keywords: forecast type, forecast category, cumulative rollup, individual rollup, quota, forecast adjustment, forecast hierarchy, opportunity splits forecasting, pipeline forecast. NOT for configuring the opportunity stages, sales processes or split types themselves — use admin/opportunity-management. NOT for territory-based forecasting setup — use admin/enterprise-territory-management. NOT for Classic/Customizable Forecasting.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 36.4 KB |
| references/examples.md | markdown | 6.5 KB |
| references/gotchas.md | markdown | 22.4 KB |
| references/llm-anti-patterns.md | markdown | 8.5 KB |
| references/metadata-examples.md | markdown | 28.1 KB |
| references/well-architected.md | markdown | 12.8 KB |
| scripts/check_collaborative_forecasts.py | script | 38.8 KB |
| templates/collaborative-forecasts-template.md | markdown | 3.6 KB |
references/well-architected.md
View on GitHub# Well-Architected Notes — Collaborative Forecasts
## Relevant Pillars
- **Operational Excellence** — Collaborative Forecasts is primarily an operational tool: it structures how forecast data flows from reps to managers to leadership. Operational excellence considerations dominate: Is the forecast hierarchy correctly mirroring the sales org? Are stage mappings kept current as the stage list evolves? Are quota loads automated and reliable? Misconfigured rollup methods, stale stage mappings, or missing forecast user enablement silently degrade the reliability of every forecast cycle.
- **Reliability** — The forecast must produce accurate and consistent data each period. The key reliability risks are: opportunity stages mapped to Omitted that should be in-pipeline, quota records with incorrect period boundary dates, and split-based opportunities with missing or incorrect split amounts. Each of these produces silent data errors — the forecast page shows no error, but the numbers are wrong.
- **Security** — Forecast visibility is governed by the forecast hierarchy, not standard sharing rules. Users can only see forecast data for their own records and their subordinates' records within the forecast hierarchy (role hierarchy or territory hierarchy). Admin users with "View All Forecasts" permission can see all forecast data. Be aware that enabling a territory-based Forecast Type does not grant additional data access beyond the territory model's sharing rules.
- **Scalability** — The four-forecast-type maximum ("The maximum number of forecast types is four", api_meta 117503) is an architectural constraint. Orgs with complex go-to-market structures (multiple geographies, multiple products, multiple sales motions) can exhaust the limit quickly. Design Forecast Types to cover the highest-value reporting dimensions; combine motions where possible before requesting a limit increase.
## Architectural Tradeoffs
**Cumulative vs Single-Category Rollup:**
Cumulative rollup is more intuitive for managers because the Commit column reflects expected revenue including already-won deals. Single-category rollup is more useful for granular pipeline analysis. The tradeoff is irreversibility. In metadata the switch is a change to `forecastedCategoryApiNames`, which "changes the organization setting for Enable Cumulative Forecast Rollups in Setup" (api_meta 117655); whether that also deletes adjustments is UNVERIFIED (2026-09-05) — the developer guides do not say. What the guides *do* document is that deactivating a type, omitting it from the XML, or disabling adjustments each purges adjustment and quota data. Treat the rollup style as a one-way architectural decision, export adjustments before touching it, and pick a low-impact window such as the start of a fiscal year. Note also that cumulative Best Case includes Most Likely, so the switch changes what a column *means*, not only how it is computed.
**Role Hierarchy vs Territory Hierarchy per Forecast Type:**
Role-based types reflect the management org chart; territory-based types reflect the coverage model. An org running both introduces complexity for users and admins because hierarchy changes (re-orgs, territory model updates) affect different Forecast Types independently. Keep the number of hierarchy types to the minimum required for stakeholder reporting.
**Forecast Types vs Standard Reports:**
Forecast Types produce manager-editable, adjustment-capable, hierarchy-based views. Standard pipeline reports produce point-in-time snapshots without adjustment context. Forecasts and reports serve different purposes; replacing one with the other causes data reconciliation confusion. Use both intentionally.
## Anti-Patterns
1. **Using a single Opportunity-Amount Forecast Type for a multi-motion sales team** — Orgs with distinct direct and overlay sales motions that try to represent both in a single Forecast Type produce misleading totals. Direct AE revenue and SE overlay revenue appear combined, potentially double-counting deals where both teams are credited. Separate Forecast Types for each motion (direct Amount vs Opportunity Splits) produce accurate, attributable numbers.
2. **Changing rollup method on a live forecast without exporting adjustments first** — Treating rollup style as a routine configuration toggle is an operational anti-pattern regardless of what the switch itself deletes, because the neighbouring settings on the same screen are documented data-loss events: `active` = false "purges all forecasting data, adjustments, and quotas for the forecast type" (api_meta 117607), omitting a type from the XML deletes its quota and adjustment data (117602), and disabling adjustments "results in adjustment data being purged" (117837). Export `ForecastingAdjustment` and `ForecastingOwnerAdjustment` before any change in this area.
3. **Skipping ForecastEnabled flag in user provisioning workflows** — Relying on role assignment alone to populate the forecast hierarchy leaves newly provisioned users invisible in forecasts. This is a systemic provisioning anti-pattern: the field must be explicitly set, and its omission produces no error — only a gap in the forecast hierarchy that may not be noticed until end of quarter.
## Official Sources Used
- **Metadata API Developer Guide, `ForecastingSettings`** (grep -n "^ *ForecastingSettings *$" api_meta.txt, 2nd hit at line 117436) — `Forecasting.settings` file name and location (117448); "The maximum number of forecast types is four" (117503); the eight required `forecastingCategoryMappings` and their rollup/source enums (117520–117560 and 117969); `forecastedCategoryApiNames` as the rollup switch (117640, 117655) and `displayedCategoryApiNames` matching it (117615, 117617); `ForecastingDateType` enum (117659); the fixed forecast-type `name` list (117722); `AdjustmentsSettings` including "Disabling adjustments results in adjustment data being purged" (117828–117852); `ForecastRangeSettings` limits and `PeriodTypes` (117910, 117913); `QuotasSettings.showQuotas` (117948); and the declarative sample the metadata examples are shaped from (117984). Supports: Before Starting, Core Concepts, `references/metadata-examples.md` §1, Gotchas 1 and 9, and every enum in `scripts/check_collaborative_forecasts.py`.
https://resources.docs.salesforce.com/262/latest/en-us/sfdc/pdf/api_meta.pdf
- **Metadata API Developer Guide, `ForecastingType` / `ForecastingSourceDefinition` / `ForecastingTypeSource` / `ForecastingFilter` / `ForecastingFilterCondition`** (api_meta.txt lines 74820–75500) — `roleType` `R`/`Y` (75264); `sourceObject`, `measureField`, `dateField`, `userField`, `categoryField`, `territory2Field` enums (75066–75129); `relationField` and the fixed parent chain (75413); "a forecast type can contain up to three filter conditions" (75041) and "Only AND is supported" (74848); and the two Usage rules that drive the release plan — "Deploy the zip file twice to create and activate the forecast type" and "Legacy forecast types that were available before API version 52.0 can be deactivated but not activated, created, or deleted" (75360–75364). Supports: `references/metadata-examples.md` §2 and §5, Gotcha 11, Recommended Workflow step 5.
https://resources.docs.salesforce.com/262/latest/en-us/sfdc/pdf/api_meta.pdf
- **Metadata API Developer Guide, `CustomValue` / `StandardValueSet`** (api_meta.txt line 47578 for `forecastCategory`, 79289 for the `GlobalPicklistValue` repeat, 47611 for `won`, 130788 for the `OpportunityStage` sample) — the deployable stage forecast-category enum `Omitted` / `Pipeline` / `BestCase` / `Forecast` / `Closed`, and "When you deploy a StandardValueSet, this array must contain at least one picklist value." Supports: Gotcha 10, `references/metadata-examples.md` §3, and the stage check in the checker script.
https://resources.docs.salesforce.com/262/latest/en-us/sfdc/pdf/api_meta.pdf
- **Object Reference, `ForecastingQuota`** (grep -n "^ *ForecastingQuota *$" object_reference.txt, 5th hit at line 147887) — the Managed Quotas permission and the "users can only edit their subordinates' … not their own" rule (147888); `StartDate` "can include any day in a given month. Stored using the first date of the month" (148027) — which is why Gotcha 5 was rewritten; `PeriodId` "Read only" (147978); `IsAmount` / `IsQuantity` with no Create property (147946, 147955). Supports: Core Concepts § Quotas, Gotcha 5, the quota CSV in `references/metadata-examples.md` §4 and the CSV lint in the checker.
https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_forecastingquota.htm
- **Object Reference, `ForecastingItem`** (line 147263) — `ForecastingItemCategory` giving the exact composition of every rollup column, including `BestCaseForecast` = Best Case + Most Likely + Commit + Closed (from 147384); "In organizations using cumulative forecast rollups, the `ForecastCategoryName` field can be null" (147423); and the access guidance "Users without the 'View All Forecasts' permission have access to all fields for their own subordinates and child territories" (147269–147271). Supports: the corrected cumulative-rollup table in SKILL.md, Gotchas 12 and 13, verification query 7.
https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_forecastingitem.htm
- **Object Reference, `ForecastingAdjustment` (145555), `ForecastingOwnerAdjustment` (147630), `ForecastingType` (148676)** — the manager-vs-owner distinction the two objects encode; `AdjustmentNote` "maximum length is 255 characters. This field doesn't appear in reports" (145600); the standard category list plus "You can add a Most Likely category and can customize forecast category names in single category rollups" (147671); `IsActive`, `IsPlatformType` (148811), `HasAdjustments` (148759), `DeveloperName` "is called `name` in the Metadata API" (148741). Supports: Core Concepts § Forecast Adjustments, the audit-mode SOQL, Gotchas 11 and 13.
https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_forecastingadjustment.htm
- **Object Reference, `User` (`ForecastEnabled`, line 295304), `UserRole` (`ForecastUserId`, line 303412), `Territory2` (`ForecastUserId`, 287371), `OpportunityStage` (195434), `Period` (216930)** — "Indicates whether the user is enabled for forecasts"; "The ID of the forecast manager associated with this role"; the two stage vocabularies `ForecastCategory` (195466) and `ForecastCategoryName` (195492); and `Period.IsForecastPeriod` (216985), which is the real object behind forecast period boundaries — there is no `ForecastingPeriod` object in the Object Reference. Supports: the forecast-hierarchy verification queries, Gotchas 5, 7, 8 and 10, and the user-CSV check.
https://developer.salesforce.com/docs/atlas.en-us.object_reference.meta/object_reference/sforce_api_objects_userrole.htm
- **Pipeline Forecasting Implementation Guide (PDF)** — user enablement and Allow Forecasting, the Forecasts Hierarchy page's Enable Users / Assign Manager actions, and the View Roles and Role Hierarchy requirement quoted in Gotchas 7 and 8. Supports: Mode 1 Step 5, Mode 3, Gotchas 7 and 8.
https://resources.docs.salesforce.com/260/latest/en-us/sfdc/pdf/forecasts.pdf
- **Salesforce Help — Set Up Collaborative Forecasts, Define Forecast Types, Forecast Categories, Cumulative Forecast Rollups, Forecast Hierarchy, Define Forecast Managers** — the Setup-side navigation and the rollup-switch adjustment-deletion claim now marked UNVERIFIED (2026-09-05) because neither developer guide states it. help.salesforce.com cannot be fetched in this environment, so these are carried as prior sourcing, not re-verified. Supports: Mode 1 and Mode 2 navigation steps, Gotcha 1's caveat.
https://help.salesforce.com/s/articleView?id=sf.forecasts3_setting_up_forecasting.htm
- **Salesforce Well-Architected** — the Operational Excellence / Reliability / Security framing used in the Relevant Pillars section above.
https://architect.salesforce.com/docs/architect/well-architected/guide/overview.html
### Checked and not found
- **Salesforce App Limits Cheat Sheet** — `grep -n -i "forecast" salesforce_app_limits_cheatsheet.txt` returns **zero hits**. No forecasting limit in this package rests on the cheat sheet. The four-forecast-type maximum is grounded in the Metadata API guide instead (api_meta 117503), and the "raise the limit through a Support case" route is recorded as UNVERIFIED.
- **`ForecastingPeriod`** — not an object in the Object Reference. Earlier guidance to query it has been replaced with `Period WHERE IsForecastPeriod = TRUE`.
- **Edition restriction** — no statement in either developer guide limits Collaborative Forecasts to Enterprise / Performance / Unlimited; `ForecastingType.DateType` lists Professional Edition for API 57.0+ custom-date types. Recorded as UNVERIFIED in SKILL.md rather than repeated.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |