Document behavior for negative and missing savings values in cost calculations

[arthurclares]

⚠️ Problem

There is currently no documentation explaining how negative savings or missing prices are handled in cost optimization calculations, particularly in scenarios where savings are shown using Power BI or Azure Data Explorer (ADX).

We are standardizing the behavior as follows:

• Negative savings will be shown if the effective price is higher than the list or negotiated price.
• Missing prices will result in 0 savings, since no valid comparison can be made.

Without documentation, users may misinterpret negative values as bugs or assume 0 savings always means no opportunity exists. We need to provide clear guidance to help users understand:

• Why negative savings are possible and valid.
• When and why savings show as 0.
• How to interpret the results correctly in reports.

This documentation is essential to build trust in the data and avoid confusion when reviewing cost-saving recommendations.

🛠️ Solution

We will create a new documentation section—either in an existing Cost Optimization or Reporting Behavior page—detailing how savings values are calculated and displayed.

The documentation should include the following:

1. Clear Definitions

• Negative savings: Occur when the effective price paid is higher than the list price or negotiated price. This is valid and indicates a potential misconfiguration or unusual pricing scenario. It will be displayed as a negative number in reports (e.g., -$100).
• 0 savings: Shown when no list or reference price is available for comparison. This means we cannot determine whether the user overpaid or saved—so we show 0 to avoid misleading results.

2. Rationale

• Why show negative savings?
  • It reflects the reality of the data and can help identify pricing anomalies or issues with contract configurations.
  • Hiding or zeroing these values would mask real cost concerns.
• Why show 0 savings for missing values?
  • If the price is missing or 0, there's no reliable basis for calculating savings.
  • It ensures math consistency without introducing misleading information.

3. Example Comparison

List Price	Effective Price	Savings Displayed
100	100	0
100	80	20
100	120	-20
Missing	80	0

4. Display Guidance

• If negative savings are shown, a small tooltip or note should be added in the UI:

  Savings may appear negative if the effective price is higher than the list or negotiated price. This may indicate pricing misconfigurations or unexpected billing conditions.

• Add links or references to this documentation so users can understand the logic without opening a support case.

5. Clarity on Totals

• When negative savings are included, totals will reflect the actual sum of all items (including negative values).
• If prices are missing and 0 savings are shown, the total will be lower than expected. This is expected and should be documented.

ℹ️ Additional context

This decision was made after internal discussion across engineering and cost optimization teams to ensure consistent behavior across reporting tools. Aligning ADX and Power BI reporting behavior is critical, and documentation will support broader adoption and understanding.

🙋‍♀️ Ask for the community

We could use your help:

1. Please 👍 this PR if you've seen confusion around savings calculation behavior.
2. Suggest clearer ways to phrase user-facing documentation or UI tooltips.
3. Share feedback if this behavior has helped identify issues or if it created confusion in your reports.