FinOps — Effective ADLC Usage
Cost visibility drives culture. 4-way validation (API vs CLI vs MCP vs Console) ensures ≥99.5% accuracy. FinOps Foundation FOCUS 1.2+ compliance. Never hardcode calendars — use relative date logic (Karpathy Rule: think before coding).
Project Identity
| Aspect | Value |
|---|---|
| Module | cloudops/finops + /Volumes/Working/projects/finops-focus |
| Framework | FOCUS 1.2+ (FinOps Foundation specification) |
| Data SSOT | Cost Explorer portal CSV (not API alone) |
| CLI Group | /finops:* commands (9 commands) |
| Sub-Product | FinOps (FO-* story prefixes in JIRA) |
Consumption Pattern
The finops module extends cloudops/runbooks:
- Inherits 38 agents, 141 commands, 128 skills from framework
/finops:*commands (9) + supporting cost analysis skills- READONLY-only execution — autonomous via
$AWS_BILLING_PROFILE+$AWS_MANAGEMENT_PROFILE+ per-workload profile - MCP atlassian-tools for JIRA publishing, JIRA Cost Explorer linked board
- Persona-mode output: CFO (executive), CTO (technical), FinOps Analyst (detailed)
Golden Path: Collect → Validate → Analyze → Report → Optimize
See docs/docs/golden-paths/finops-analytics-lifecycle.md (5-phase loop):
- Collect (3 min) — READONLY profiles + FOCUS 1.2+ normalization. Never hardcode
/30days. - Validate (15 min) — 4-way cross-validation: CLI vs Config Aggregator vs Cost Explorer vs Console (≥99.5% target).
- Analyze (30 min) — Cost by account, service, commitment, anomalies (ThreadPoolExecutor for pipelined org-wide queries).
- Report (10 min) — Persona-specific exports: CFO, CTO, CloudOps Engineer. CSV + JSON + Confluence.
- Optimize (varies) — Execute recommended decommissions, reservations, commitment adjustments (per cost-saving KR).
Effective Commands (FinOps)
| Command | Purpose | Input | Output | Quality Gate |
|---|---|---|---|---|
/finops:aws-monthly --profile ops-account --period YYYY-MM`` | AWS cost report with FOCUS 1.2+ normalization | Cloud profile + calendar period | CSV, JSON, persona views (CFO/CTO/Engineer) | All accounts visible, ≥99.5% MCP accuracy |
/finops:azure-monthly --subscription {id} --period YYYY-MM`` | Azure cost report with multi-cloud normalization | Azure subscription + period | Persona-mode export + cross-cloud comparison | Same FOCUS tags as AWS |
/finops:analyze --metric anomalies | Cost anomaly detection (spike + gradual trends) | Prior 3-month baseline | Recommended actions with $ impact + owner | Pct change >15% or >$5K |
/finops:decommission-inventory --decommission-status active | E2-E7 decommission signals per decommission_scorer.py | Live AWS account state | Resource list with signal scores + recommendations | 4-way agreement ≥99.5% |
/finops:commit-planner --cloud aws --period 2026-05 | Savings plan + reserved instance recommendations | Usage trends + current commitments | Recommendations ranked by ROI | Payback period <12 months |
4-Way Cross-Validation Framework (99.5% Target)
Core principle: No single source is authoritative. Validate ≥2 independent sources.
| Source | API/Tool | What It Measures | Gotchas |
|---|---|---|---|
| AWS Cost Explorer | aws ce get-cost-and-usage (READONLY) | Billing portal data (SSOT) | RBAC-scoped: billing role sees all; ops role sees 0 cross-account |
| Config Aggregator | aws configservice batch-get-aggregate-resource-count (centralised-ops account) | Real-time resource counts (E1 signal) | Org-wide discovery only; not account-level (prevents SINGLE_ACCOUNT_ASSUMPTION) |
| CloudTrail Lake | aws athena queries on CloudTrail lake (ops account) | API call history (E5 activity validation) | >24h lag; requires log archive setup |
| Console Output | runbooks inventory --all --output table | Human-readable resource listing | Terminal rendering (use Rich export_html for evidence) |
Validation Rules:
- Cross-Account queries MUST verify account match (avoid
CROSS_ACCOUNT_SILENT_ZERO) - Cost Explorer CSV is SSOT if API returns 0 (avoid
FINOPS_API_SSOT_MISMATCH) - ≥2 sources must agree within 2% margin (MCP reported accuracy: see evidence JSON)
Calendar Math (Critical Lesson — 2026-03-21)
Anti-pattern: Hardcoded /30 day normalization. Results in:
- February undercounts by 6.7% (28 days vs 30)
- 31-day months undercounts by 3.3%
- Year-over-year trend charts show phantom 5% swings
Rule: Use parse_billing_period_to_days() for actual calendar days.
# CORRECT: Compute actual days in period
def normalize_daily_cost(monthly_total: float, year: int, month: int) -> float:
import calendar
days_in_month = calendar.monthrange(year, month)[1]
return monthly_total / days_in_month
# WRONG: Hardcoded denominator
daily_cost = monthly_total / 30 # BUG: 3.3-6.7% undercounts
Cost Reconciliation ($ Numbers Must Match)
Every deliverable with financial claims requires reconciliation to Cost Explorer CSV:
| Deliverable Type | Reconciliation Method | Evidence File |
|---|---|---|
| CFO Report (executive summary) | Export Cost Explorer CSV for period. Spot-check ≥3 accounts. | evidence/finops-cost-explorer-{YYYY-MM}.csv |
| Cost Anomaly Analysis | Run /finops:analyze --metric anomalies 2x. Results must agree ±1%. | evidence/finops-anomalies-comparison-{date}.json |
| Decommission Savings | Cost Explorer: sum costs of decommissioned resources for prior 12 months. | evidence/finops-decommission-payback-{resource_id}.csv |
| Commitment Recommendations | RI/SP payback <12 months verified against actual usage history (3 months). | evidence/finops-commitment-historical-usage-{YYYY-MM}.csv |
Quality Gate: Every $ claim includes reconciliation evidence path. No "estimate" or "TBD" placeholders.
Persona-Specific Reporting
| Persona | Time Budget | Focus | Deliverable Format |
|---|---|---|---|
| CFO (Cost-Out) | 5 min read | Total spend trend, top 3 cost drivers, YoY %, savings opportunity ($) | Executive summary: 3 bullets + 1 chart (Vizro) |
| CTO (FinOps Culture) | 15 min read | Architecture cost breakdown (compute vs storage vs data), commitment utilization %, reserved instance coverage | Technical dashboard: 5 tables (Rich format) |
| FinOps Analyst (Detailed) | 30 min read | Per-service cost, daily trend, hourly spike details, anomaly flags, optimization backlog | Jupyter notebook + CSV export for modeling |
Anti-pattern: Publishing raw Cost Explorer tables to CFO. Results: no action, lost credibility. Always synthesize to 3-bullet executive summary.
CxO Quality Gate: Reconciliation + Narrative
Every FinOps deliverable for HITL/CxO review requires:
- Reconciliation: Cost Explorer CSV export with ≥3 accounts spot-checked
- Narrative: "Cost rose 12% MoM (Feb→Mar). Drivers: [service % each]. Savings opportunity: $X [action list]."
- Ownership: Every recommendation includes [Owner], [Timeline], [Approval Level]
- Risk callout: Plain English, not severity codes (e.g., "Could stop production overnight if database commitment lapses" not "F4 MEDIUM")
READONLY Execution (Autonomous)
FinOps team executes autonomously with READONLY profiles. HITL not in loop for data collection (anti-pattern: READONLY_HITL_HANDOFF):
$AWS_BILLING_PROFILE→ Cost Explorer only (pre-authorized for /finops queries)$AWS_MANAGEMENT_PROFILE→ Organizations API only (pre-authorized for org-wide discovery)- Per-workload profile (from ~/.aws/config) → CloudWatch, CloudTrail, SSM (pre-authorized for E2-E6 signals)
All three profiles = pre-authorization. Enterprise team runs commands, publishes results to Confluence, escalates findings to HITL.
Anti-Patterns Specific to FinOps
| Anti-Pattern | Example | Prevention |
|---|---|---|
FINOPS_API_SSOT_MISMATCH | API returns 0 cross-account; report says "clean" | Rules-layer: Cost Explorer CSV is SSOT; validate account match first |
DRYRUN_OVER_READONLY | Use --dry-run instead of real READONLY profile | Rules-layer: L3 real execution > L1 --help validation |
CROSS_ACCOUNT_SILENT_ZERO | Org-wide query from ops account returns 0; assumed clean | Rules-layer: verify sts get-caller-identity matches expected account |
HARDCODED_ENV_IN_PRODUCT_DOCS | Doc hardcodes "$45,000 monthly budget" for one account | Hook detect-hardcoded-env-data.sh blocks (exit 2); use placeholders |
Testing & Validation (FinOps-Specific)
All /finops:* commands tested against:
- Snapshot tests (L1) — Mock AWS cost-and-usage responses, verify calculation logic
- LocalStack (L2) — Mock multi-account org, verify Config Aggregator queries
- Live READONLY (L3, daily) — Real Cost Explorer data + ops account, 4-way cross-validation ≥99.5%
Evidence files published to tmp/finops/{layer}-evidence.json with:
- Accuracy (% match vs Cost Explorer CSV SSOT)
- Validation method (which 4-way sources compared)
- Timestamp + period (
YYYY-MM)
Real Software Deliverables (2026-2030)
- Monthly Reports (Confluence) — CFO, CTO, FinOps Analyst persona views
- Decommission Inventory (CSV) — E2-E7 scores, resource IDs, cost attribution, payback calc
- Cost Anomaly Dashboard (Vizro or Rich export) — Daily spike detection, trend analysis
- Commitment Recommendations (JIRA FO board) — RI/SP candidates, payback period, approval workflow
- Multi-Cloud Normalized Data (FOCUS 1.2+ CSV) — AWS + Azure cost harmonized by cost dimension
References
- Golden Path:
docs/docs/golden-paths/finops-analytics-lifecycle.md(5-phase Collect→Validate→Analyze→Report→Optimize) - Framework:
CLAUDE.md(root) → cloudops submodule + finops extension - Cost Profile Semantics:
.claude/rules/engineering/aws-profile-semantics.md(BILLING vs MANAGEMENT vs per-workload) - Operational Efficiency:
.claude/rules/governance/operational-efficiency.mdRule 6 (AWS API resilience: pagination, retry, errors) + Rule 7 (no dry-run with READONLY) - Anti-Patterns:
.claude/rules/governance/anti-patterns-catalog.md(FINOPS_API_SSOT_MISMATCH, CROSS_ACCOUNT_SILENT_ZERO, HARDCODED_ENV_IN_PRODUCT_DOCS) - FOCUS 1.2+ Spec: https://finops.org/framework/focus/ (cost dimension taxonomy)