URL: /code/files/metrics · Id: `page:/code/files/metrics`

# The metrics/ folder: one file and what it compiles to

> What one metrics/ file holds, what each key compiles to, and the checks that read it.

One `metrics/` file is the quarter’s [Goal](https://startupbuilder.dev/business/nouns/goal) and [Key Results](https://startupbuilder.dev/business/nouns/key-result), and each leaf [Metric](https://startupbuilder.dev/business/nouns/metric) with its one parent. SalesBuilder compiles it, and `show` traces every key.

```mdx title="metrics/q4.mdx"
---
goal: { objective: "Reach $25k ARR by year end", horizon: quarter }
keyResults:
  - { metric: net-new-arr, baseline: 0, target: 1800, deadline: 2026-12-31 }
  - { metric: opened-deals-and-trials, baseline: 2, target: 6, deadline: 2026-12-31, role: sales/prospector }
---
```

```text title="show"
$ npx startup-builder show metrics/q4.mdx
goal        { objective: "Reach $25k ARR by year end", horizon: quarter }  metrics/q4.mdx:2
keyResults                                                                 metrics/q4.mdx:3
parent      new-leads                                                      metrics/positive-reply-rate.mdx:2
owner       SalesBuilder
```

```text title="leaseline.app"
leaseline.app/
├── plays/
│   ├── cold-email.mdx
│   ├── warm-intros.mdx
│   ├── signup-interviews.mdx
│   ├── lead-reactivation.mdx
│   └── events-and-webinars.mdx
├── audiences/
│   ├── small-property-managers.mdx
│   ├── lapsed-leads.mdx
│   └── renewal-season.mdx
├── sequences/
│   └── cold-email-thread-founder.mdx
├── funnels/
│   └── signup.mdx
├── workflows/
│   └── outbound.mdx
├── agents/
│   ├── sales/prospector.mdx
│   └── marketing/content-lead.mdx
├── systems/
│   └── sequences.mdx
├── domains/
│   └── leaseline.app.mdx
├── offers/
│   ├── pro.mdx
│   └── team.mdx
├── content/
│   └── webinars/60-day-notices.mdx
├── metrics/   ← this folder
│   ├── q4.mdx
│   └── positive-reply-rate.mdx
└── startups.lock
```

## The file
| Key | On the page | Compiles to | Checked by |
| --- | --- | --- | --- |
| `goal` | Goal | the quarter’s objective and horizon | — |
| `keyResults` | Key Results | each a node or leaf with baseline, target and deadline; one with a `role` lands in that seat’s number | [S9](/code/checks#s9) |
| `parent` | Parent | in a leaf’s own file: its one parent, so its chain reaches `arr` | [S1](/code/checks#s1) |

## Checks
| Check | It holds | What dev prints |
| --- | --- | --- |
| [S1](/code/checks#s1) | The Metric’s parent chain reaches `arr`: the Result card’s path. | `metrics/q4.mdx:5  S1  keyResults[1].metric: demo-requests has no parent chain to arr. Set its parent: opened-deals-and-trials.` |
| [S9](/code/checks#s9) | Each Key Result names a node or leaf of the ARR tree, and a seat’s Key Result sits in its band. | `agents/sales/prospector.mdx:4  S9  results: reply-count is not a node or leaf of the ARR tree. Did you mean positive-reply-rate?` |

## Refusals
| Code | Fix, then the call that clears it |
| --- | --- |
| [`baseline`](/code/refusals#check-baseline) | Read the last 90 days first; thin history reads before-after, not proof. Then <Op verb="Metric.query" />. |
| [`recompute`](/code/refusals#check-recompute) | Recompute the Metric, then render the log again. Then <Op verb="Metric.query" />. |
| [`scale-gate`](/code/refusals#check-scale-gate) | Wait for the holdout readout to win, then raise it. Then <Op verb="Metric.query" />. |
| [`step-gate`](/code/refusals#check-step-gate) | Wait for cost per trial to fall under the line, then sign. Then <Op verb="Metric.query" />. |
| [`stripe-revenue`](/code/refusals#check-stripe-revenue) | Query the revenue from live-mode Stripe, then compile the log. Then <Op verb="Metric.query" />. |
| [`use-when`](/code/refusals#check-use-when) | Run the Play Not yet when names, or wait until the volume is there. Then <Op verb="Metric.query" />. |

## Calls

```text title="metrics/ compiled · Ask"
Define the leaf Metric and read its trend.
```

```ts title="metrics/ compiled · SDK"
import { $ } from 'startup-builder'

await $.Metric.define({ name: 'Leaseline', query: 'Example query', unit: 'Example unit' }, { mode: 'try' })   // metrics/positive-reply-rate.mdx
return await $.Metric.query({ metric: 'positive-reply-rate', shape: 'trend', window: '28d' })   // parent new-leads, up to arr
```

```json title="metrics/ compiled · Response · sample"
{
  "rows": {},
  "metric": {
    "$id": "https://api.sb/leaseline.app/metrics/metric_1",
    "$type": "Metric",
    "query": "Example query",
    "status": "draft"
  },
  "action": {
    "$id": "https://api.sb/leaseline.app/actions/action_1",
    "operation": "Metric.query",
    "status": "done"
  }
}
```

| Call | What it does |
| --- | --- |
| <a id="metric-define"></a><Op verb="Metric.define" /> | Define compiles a Metric’s query against the Startup’s Events and Entries and lists every Event it reads. Emits [`Metric.defined`](/code/events#metric-defined). |
| <a id="metric-query"></a><Op verb="Metric.query" /> | Query reads Metrics or Events as a trend, funnel, retention curve, path or lifecycle, broken down by any property. Emits [`Metric.queried`](/code/events#metric-queried). |
| <a id="metric-watch"></a><Op verb="Metric.watch" /> | Watch alerts the owner of a Metric when it crosses a threshold, by a Task or a Message. Emits [`Metric.watched`](/code/events#metric-watched). |