---
name: demo-plan
description: Create billing data generation configs for a demo scenario. Guides through requirements, feature design, config writing, and validation.
---

# /demo-plan

You are helping a Sales Engineer create CZBG generate configs. You write
the YAML files — the SE describes what they need conversationally.

**You never submit jobs.** The SE uses `/demo-generate` after configs are ready.

## Before You Start

Read the reference docs bundled with this skill:

| Doc | What it gives you |
|-----|-------------------|
| [reference/cost-configuration.md](reference/cost-configuration.md) | total_cost rules, anomaly mechanics, resource groups, filter hierarchy, K8s constraints, line item limits |
| [reference/variance-v2-templates.md](reference/variance-v2-templates.md) | All 17 cost pattern templates with YAML definitions |
| [reference/provider-patterns.md](reference/provider-patterns.md) | Account formats, regions, tags, K8s naming per provider |
| [reference/feature-catalog.md](reference/feature-catalog.md) | Workload archetypes with service stacks and budget refs |
| [reference/telemetry-generation.md](reference/telemetry-generation.md) | Unit metric and allocation telemetry config format |

Also read the example configs in `examples/` — copy filter blocks from
these, never invent filter strings.

## Rules

1. **Never submit a job** — authoring only.
2. **Always validate** with `czbg analyze config --json` after writing configs.
3. **Never invent filter strings** — copy from `examples/` for exact service
   names, usage families, resource types, operations, and usage types.
4. **Never use empty `usage_types: []`** — matches ALL, causes line item explosion.
5. **GCP requires `operations: []`** — empty list, not null.
6. **`total_cost` is for the entire date range**: `monthly_spend × months`.
7. **Anomaly jobs need `target_anomaly_cost`** on the anomaly_profile.
   See [reference/cost-configuration.md](reference/cost-configuration.md).
8. **Line item limit**: <10M per provider (aggregate across all jobs).
   See [reference/cost-configuration.md](reference/cost-configuration.md).
9. **K8s constraints**: 80 compute resources, 5 clusters, 3 namespaces, 3 workloads.
   See [reference/cost-configuration.md](reference/cost-configuration.md).
10. **Every config needs `reference_data_source: s3`** as the first field.
11. **Quote YAML values with colons**: `"Cloud SQL: Backups in Frankfurt"`.
12. **Organize configs by demo**: `configs/{demo-name}/{provider}/{category}/generate/{feature}/{service}.yaml`
    where category is `base`, `optimize`, `anomalies`, or `unit-econ`.
13. **Telemetry configs** use `telemetry:` block on generate jobs, not separate files.
    See [reference/telemetry-generation.md](reference/telemetry-generation.md).

## Workflow

### Step 1: Gather Requirements

Ask the SE (skip what they've already provided):

- **Demo name**: short slug for the config directory (e.g., `acme-corp`, `fintech-demo`)
- **Demo scenario**: What's the demo for?
- **Cloud providers**: AWS, GCP, Azure — which ones?
- **Monthly spend target**: approximate total (e.g., $500K/month)
- **Date range**: start and end (default: 12 months from Jan 1 of current year)
- **Cost story** (optional): growth, optimization, anomaly spike, step-up/down
- **Unit economics** (optional): cost-per-transaction, cost-per-API-call, shared
  cost allocation? If yes, the configs will need telemetry blocks.
- **Tag messiness** (optional): demonstrate CloudZero tag normalization?
  (default: yes — see [reference/provider-patterns.md](reference/provider-patterns.md)
  for the 4-level messiness pattern)

### Step 2: Design Feature Plan

Read [reference/feature-catalog.md](reference/feature-catalog.md) for proven
workload archetypes. If the SE has their own design, use that instead.

Map the scenario to features. For each, determine:
- Service categories per provider
- Cost split (compute typically 40-60%, storage 15-25%)
- Cost pattern template (see [reference/variance-v2-templates.md](reference/variance-v2-templates.md))
- Resource counts (see [reference/cost-configuration.md](reference/cost-configuration.md) for realism targets)
- Whether telemetry is needed (unit metrics or allocation)

Present a feature plan table and proposed config file structure. Wait for
the SE to confirm before writing any YAML.

### Step 3: Discover Filter Blocks

For each provider the SE needs, get exact filter blocks from the reference data.

**If an example exists** (`examples/{provider}/`), read it and copy the `filters` block:

```bash
cat examples/aws/compute.yaml
```

**If no example exists** (SaaS providers, newer providers), discover filters via CLI:

```bash
# List available services for the provider
czbg data explore combinations --cloud-provider MongoDB

# Get copy-pasteable YAML filter block for a specific service
czbg data explore combinations \
  --cloud-provider MongoDB \
  --service "Atlas M60 Instance - AWS" \
  --format yaml
```

Use your judgment to select services appropriate for the SE's spend target and
scenario. You know what these services do — pick the ones that tell the right
cost story and distribute budget realistically.

Also read [reference/provider-patterns.md](reference/provider-patterns.md) for
account IDs, regions, and tag formats for AWS/GCP/Azure. For SaaS providers,
the CLI output shows what's available — use the explore output to determine
the provider's operations pattern (null vs specific), usage family convention,
and resource type naming.

### Step 4: Write Configs

Write configs following the demo directory convention:

```
configs/{demo-name}/{provider}/{category}/generate/{feature}/{service}.yaml
```

Where `category` is one of:
- `base` — standard workload billing (compute, storage, database, managed services)
- `optimize` — optimization recommendation scenarios
- `anomalies` — anomaly spike/step-change scenarios
- `unit-econ` — unit economics and telemetry scenarios

For example, an Acme Corp demo with AWS EC2 compute for an InsightAPI feature:
```
configs/acme-corp/aws/base/generate/insightapi/compute.yaml
```

For guidance on config structure, see
[reference/cost-configuration.md](reference/cost-configuration.md).

If the SE needs telemetry, add `telemetry:` blocks to the relevant generate
jobs. See [reference/telemetry-generation.md](reference/telemetry-generation.md)
for the config format.

### Step 5: Validate

```bash
czbg analyze config configs/{demo-name}/ --json
```

Parse the JSON. For every job in `job_analyses`:
- `job_config.reference_match_count` must be > 0
- Sum `peak_month_line_items` per provider across all jobs — must be < 10,000,000

If blocked, fix and re-validate. Also show the human-readable output:

```bash
czbg analyze config configs/{demo-name}/
```

### Step 6: Finalize

When all jobs pass validation:
> "Configs saved to `configs/{demo-name}/`. Use `/demo-generate configs/{demo-name}/` when ready to submit."
