# Report Spec Format

Every report resolves to this structure before any data is pulled. The spec is what gets saved, and it's what makes a report repeatable.

---

## The format

```
Report name:  <short, owner-recognizable>
Cadence:      one-off | weekly | monthly | quarterly
Period:       <the window each run covers>
Comparison:   <prior period | same period last year | target | none>
Grouping:     <dimension, or none>

Metrics:
  <name>  =  <formula>  [source]
  <name>  =  <formula>  [source]

Sources:      <connectors used, or "uploaded file">
Notes:        <anything the owner clarified>
```

---

## Worked example 1 — the classic

**Owner said:** "Every Monday: sales by location vs last year, AR aging, labor percent."

```
Report name:  Monday operating pack
Cadence:      weekly, Monday
Period:       trailing 7 days
Comparison:   same 7 days last year
Grouping:     location

Metrics:
  Sales          =  sum of invoice totals, excluding tax   [QuickBooks]
  AR aging       =  open invoices bucketed 0-30 / 31-60 / 61+ days past due   [QuickBooks]
  Labor percent  =  payroll expense / net revenue          [QuickBooks]

Sources:      QuickBooks
Notes:        Labor measured against revenue, not total costs (confirmed).
              AR aging is company-wide, not split by location.
```

Note what was inferred and what was asked. Metric, grouping, and comparison came straight from the sentence. Only the labor denominator and the AR grouping needed a question.

---

## Worked example 2 — no connectors

**Owner said:** "I need a monthly report showing which products make the most money."

```
Report name:  Monthly product profitability
Cadence:      monthly, first business day
Period:       prior calendar month
Comparison:   prior month
Grouping:     product

Metrics:
  Revenue       =  sum of line totals by SKU        [uploaded sales CSV]
  Units         =  sum of quantity by SKU           [uploaded sales CSV]
  Gross margin  =  (revenue - COGS) / revenue       [uploaded sales CSV]

Sources:      uploaded file — monthly sales export
Notes:        COGS column must be present in the export. If absent, report
              revenue and units only and say margin is unavailable.
```

The no-connector path produces exactly the same shape of spec. Nothing about the report is degraded except where the data itself is missing.

---

## Worked example 3 — pipeline, cross-source

**Owner said:** "Show me every month how the pipeline is converting and what it's actually worth."

```
Report name:  Monthly pipeline conversion
Cadence:      monthly
Period:       prior calendar month
Comparison:   prior month
Grouping:     deal stage

Metrics:
  Deals entered     =  count of deals created in period       [HubSpot]
  Deals won         =  count of deals closed-won in period    [HubSpot]
  Win rate          =  deals won / deals resolved             [HubSpot]
  Weighted pipeline =  sum of (deal value x stage probability) [HubSpot]
  Revenue realized  =  invoices paid in period                [QuickBooks]

Sources:      HubSpot, QuickBooks
Notes:        Revenue realized is deliberately from the books, not the CRM.
              CRM deal values are forecasts; invoices are facts.
```

---

## Rules that keep specs honest

**Every metric names its source.** A metric without a source is a metric nobody can reproduce next month.

**Formulas are written out, not implied.** "Labor percent" means nothing on its own. "Payroll expense divided by net revenue" can be checked.

**Ambiguity gets recorded in Notes, not silently resolved.** When the owner clarifies something, write down what they said. Six months later that note is the only record of why the number is calculated the way it is.

**One report, one purpose.** If an owner describes eight unrelated metrics, that is probably two reports. Suggest the split rather than building one unreadable pack.