Azure Cost Estimate Documentation Standards

Azure Cost Estimate Documentation Standards

Document Purpose

Cost estimates provide:

• Financial clarity for budget approvals
• Architecture context linking cost to design decisions
• Optimization guidance for reducing costs
• Fast decisions via "what changes cost" tables

General Requirements

• Keep markdown lines <= 120 characters.
• Use ATX headings (##, ###) for sections.
• Use emoji callouts consistently (see "Visual Standards").
• Prefer tables for compare-and-decide content.
• If the workload is small, keep the same sections but shorten them.

Canonical Templates (Golden Source)

The canonical cost-estimate structure is defined in these templates:

• .github/templates/03-des-cost-estimate.template.md (design estimate)
• .github/templates/07-ab-cost-estimate.template.md (as-built estimate)

Agents MUST start from the appropriate template and fill it in. Do not re-embed long templates in agent bodies.

Core Heading Contract (Stable)

Both templates MUST contain these exact H2 headings (##) in this order:

1. ## 💰 Cost At-a-Glance
2. ## ✅ Decision Summary
3. ## 🔁 Requirements → Cost Mapping
4. ## 📊 Top 5 Cost Drivers
5. ## Architecture Overview
6. ## 🧾 What We Are Not Paying For (Yet)
7. ## ⚠️ Cost Risk Indicators
8. ## 🎯 Quick Decision Matrix
9. ## 💰 Savings Opportunities
10. ## Detailed Cost Breakdown

Notes:

• Emoji + spacing must match exactly.
• Use the unicode arrow → (not ->) in the Requirements heading.
• Additional H2 headings are allowed, but discouraged (prefer H3s).

Required Header

# Azure Cost Estimate: {Project Name}

**Generated**: {YYYY-MM-DD}
**Region**: {primary-region}
**Environment**: {Production|Staging|Development}
**MCP Tools Used**: {azure_price_search, azure_cost_estimate, azure_region_recommend, azure_sku_discovery}
**Architecture Reference**: {relative link to assessment doc, if available}

💰 Cost At-a-Glance (Required)

Include immediately after the header:

## 💰 Cost At-a-Glance

> **Monthly Total: ~$X,XXX** | Annual: ~$XX,XXX
>
> ```
> Budget: $X/month (soft|hard) | Utilization: NN% ($X of $X)
> ```
>
> | Status            | Indicator                    |
> | ----------------- | ---------------------------- |
> | Cost Trend        | ➡️ Stable                    |
> | Savings Available | 💰 $X/year with reservations |
> | Compliance        | ✅ {e.g., PCI-DSS aligned}   |

If no budget is provided, use:

• Budget: No fixed budget (explain in one sentence)

✅ Decision Summary (Required)

Immediately after "Cost At-a-Glance", include a 2-3 bullet decision summary:

• What's approved now
• What's deferred (intentionally not paying for yet)
• What requirement change would trigger a redesign

Also include a confidence line:

**Confidence**: High|Medium|Low | **Expected Variance**: ±X% (1 sentence why)

Visual Standards

Status Indicators

Category Icons

Trend Indicators

• ➡️ Stable
• 📈 Increasing
• 📉 Decreasing
• ⚠️ Volatile/unknown

Required Sections (Recommended Order)

1. ✅ Decision Summary

## ✅ Decision Summary

- ✅ Approved: {what is in-scope and funded}
- ⏳ Deferred: {what is explicitly not included yet}
- 🔁 Redesign Trigger: {what requirement change forces SKU/region redesign}

**Confidence**: High|Medium|Low | **Expected Variance**: ±X% (1 sentence why)

2. 🔁 Requirements → Cost Mapping

Map business requirements and NFRs to concrete SKU decisions.

## 🔁 Requirements → Cost Mapping

| Requirement | Architecture Decision | Cost Impact  | Mandatory |
| ----------- | --------------------- | ------------ | --------- |
| SLA 99.9%   | Use {service/SKU}     | +$X/month 📈 | Yes       |
| RTO/RPO     | {backup/DR choice}    | +$X/month    | No        |
| Compliance  | {WAF/PE/CMK choice}   | +$X/month 📈 | Yes       |

3. 📊 Top 5 Cost Drivers

## 📊 Top 5 Cost Drivers

| Rank | Resource | Monthly Cost | % of Total | Trend |
| ---- | -------- | ------------ | ---------- | ----- |
| 1️⃣   | ...      | $...         | ...        | ➡️    |

> 💡 **Quick Win**: One low-effort action that saves meaningful cost

4. Summary

## Summary

| Metric              | Value             |
| ------------------- | ----------------- |
| 💵 Monthly Estimate | $X - $Y           |
| 📅 Annual Estimate  | $X - $Y           |
| 🌍 Primary Region   | swedencentral     |
| 💳 Pricing Type     | List Price (PAYG) |
| ⭐ WAF Score        | X.X/10 (or TBD)   |
| 🎯 Target Users     | N concurrent      |

Add a short "Business Context" narrative (2-5 lines) linking spend to outcomes.

5. Architecture Overview

Include both subsections:

1. Cost distribution (Mermaid pie)
2. Key design decisions affecting cost

The cost distribution Mermaid pie is required even for very small workloads. If there are only 1-2 cost categories, still include the pie (it can be simple).

## Architecture Overview

### Cost Distribution

```mermaid
%%{init: {'theme':'base','themeVariables':{pie1:'#0078D4',pie2:'#107C10',pie3:'#5C2D91',pie4:'#D83B01',pie5:'#FFB900'}}}%%
pie showData
    title Monthly Cost Distribution ($)
    "💻 Compute" : 535
    "💾 Data Services" : 466
    "🌐 Networking" : 376
```

Key Design Decisions Affecting Cost

### 6. 🧾 What We Are Not Paying For (Yet)

Make trade-offs explicit so stakeholders see conscious deferrals.

```markdown
## 🧾 What We Are Not Paying For (Yet)

> Examples: multi-region active-active, private endpoints for all services, premium HA cache, DDoS Standard
```

### 7. ⚠️ Cost Risk Indicators

```markdown
## ⚠️ Cost Risk Indicators

| Resource | Risk Level | Issue | Mitigation |
| -------- | ---------- | ----- | ---------- |
| ... | 🔴 High | ... | ... |

> **⚠️ Watch Item**: One sentence on the biggest budget uncertainty

8. 🎯 Quick Decision Matrix

## 🎯 Quick Decision Matrix

_"If you need X, expect to pay Y more"_

| Requirement | Additional Cost | SKU Change | Notes |
| ----------- | --------------- | ---------- | ----- |
| ...         | +$.../month     | ...        | ...   |

9. 🧩 Change Control (Top 3 Change Requests)

Standardize the 3 most likely changes and their delta.

## 🧩 Change Control

| Change Request      | Delta     | Notes                |
| ------------------- | --------- | -------------------- |
| Add multi-region DR | +$X/month | From decision matrix |
| Add WAF             | +$X/month | From decision matrix |
| Upgrade DB tier     | +$X/month | From decision matrix |

10. 💰 Savings Opportunities

Always include a savings section. If already optimized, say so and list what is already applied.

## 💰 Savings Opportunities

> ### Total Potential Savings: $X/year
>
> | Commitment | Monthly Savings | Annual Savings |
> | ---------- | --------------- | -------------- |
> | 1-Year ... | $...            | $...           |

### Additional Optimization Strategies

| Strategy | Potential Savings | Effort | Notes |
| -------- | ----------------- | ------ | ----- |
| ...      | ...               | 🟢 Low | ...   |

11. Detailed Cost Breakdown

Break down by category, include subtotals.

## Detailed Cost Breakdown

### 💻 Compute Services

| Resource | SKU | Qty | $/Hour | $/Month | Notes |
| -------- | --- | --- | ------ | ------- | ----- |

**💻 Compute Subtotal**: ~$X/month

12. 📋 Monthly Cost Summary

Include:

• A category summary table
• An ASCII bar distribution (simple, readable)

13. 🧮 Base Run Cost vs Growth-Variable Cost

Make variance drivers explicit.

## 🧮 Base Run Cost vs Growth-Variable Cost

| Cost Type       | Drivers     | Examples                   | How It Scales                 |
| --------------- | ----------- | -------------------------- | ----------------------------- |
| Base run        | fixed SKUs  | App Service plan, SQL tier | step-changes (SKU upgrades)   |
| Growth-variable | usage-based | egress, logs, queries      | linear/near-linear with usage |

14. 🌍 Regional Comparison

Include the primary region and at least one alternative. Add one sentence explaining why the primary was chosen.

15. 🔧 Environment Strategy (FinOps)

Explicitly state prod vs non-prod sizing rules and whether non-prod auto-shutdown is used.

## 🔧 Environment Strategy (FinOps)

- Production: {HA/zone strategy, baseline capacity}
- Non-prod: {smaller SKUs, single instance, auto-shutdown schedule}

16. 🔄 Environment Cost Comparison

If there are multiple environments (prod/staging/dev), include the table. If single environment, include a short table and state "single environment".

17. 🛡️ Cost Guardrails

Tie the estimate to operational enforcement.

## 🛡️ Cost Guardrails

| Guardrail      | Threshold   | Action                   |
| -------------- | ----------- | ------------------------ |
| Budget alert   | 80% / 100%  | Notify / block approvals |
| DB utilization | >80%        | Review tier/queries      |
| Log ingestion  | >X GB/day   | Tune sampling/retention  |
| Egress         | >X GB/month | Investigate CDN/traffic  |

18. 📝 Testable Assumptions

List 3-5 assumptions most likely to change spend, and how to measure them.

## 📝 Testable Assumptions

| Assumption         | Why It Matters             | How to Measure            | Threshold / Trigger |
| ------------------ | -------------------------- | ------------------------- | ------------------- |
| Egress < 100 GB/mo | keeps networking costs low | Azure Cost Mgmt + metrics | >100 GB/mo          |
| Logs < 5 GB/mo     | avoids ingestion costs     | Log Analytics usage       | >5 GB/mo            |

19. 📊 Pricing Data Accuracy

Required bullets:

• Usage basis (e.g., 730 hours/month)
• Pricing type (PAYG list price unless otherwise stated)
• Data/egress assumptions
• Prices queried date

19. 📊 Pricing Data Accuracy

## 📊 Pricing Data Accuracy

> **📊 Data Source**: Prices retrieved from Azure Retail Prices API via Azure Pricing MCP
>
> ✅ **Included**: Retail list prices (PAYG)
>
> ❌ **Not Included**: EA discounts, CSP pricing, negotiated rates, Azure Hybrid Benefit
>
> 💡 For official quotes, validate with Azure Pricing Calculator

20. 🔗 References

Always include links to:

• Azure Pricing Calculator
• Azure Retail Prices API
• Any assessment/plan/docs used

Pricing Sources (Priority Order)

1. Azure Pricing MCP (azure_price_search, azure_cost_estimate)
2. Azure Pricing Calculator (manual validation)
3. Azure Retail Prices API (programmatic)

Patterns to Avoid