## TL;DR
A markdown file with your key numbers, updated weekly by a script or by hand, beats a dashboard nobody opens. It lives in version control, diffs show you exactly what changed, and writing the commentary forces you to understand the numbers. Start with ten lines: four headline metrics, three movers, and three lines of your own words.

```text
dashboard in a markdown file: the low-tech metrics habit
```

## Use this when
- You built a dashboard once and stopped opening it
- The team is small and BI tooling is overhead
- You want metrics history in version control with diffs
- A founder wants "just send me the numbers" weekly
- Your metrics fit on one screen and always will

## Not for this skill when
- You need real-time or near-real-time monitoring (different discipline)
- Many people need sliced, interactive exploration (that is BI tooling)
- Metrics access must be permissioned per viewer (a file is all-or-nothing)
- You are tracking hundreds of metrics across teams

## Steps
1. Write the file by hand once, with real numbers. Headlines with week-over-week change, what moved and your best guess why, and what you are watching next week. If it is longer than a screen, cut it; length is where dashboards go to die.
   ```text
   # Metrics 2026-10-04
   ## Headlines (vs last week)
   - weekly active agents: 312 (+8%)
   - successful queries: 4,102 (+12%)
   ## What moved
   ## Watch next week
   ```
   Expected output: one complete file. Success check: a teammate understands the week from it in two minutes.

2. Put it in version control next to the code. Dated files in one directory, or one file with dated sections; either way, git history becomes your metrics history and diffs become your change log. This is the feature no dashboard gives you for free.
   ```text
   metrics/2026-10-04.md, metrics/2026-09-27.md, ...
   ```
   Expected output: metrics directory in the repo. Success check: `git log` on the directory tells the story of the last quarter.

3. Automate the number-filling, not the thinking. A script pulls the headline numbers into the template; you still write the "what moved" section by hand every week. Automating the commentary produces confident-sounding nonsense.
   ```text
   [ ] script fills headlines from data sources
   [ ] human writes movers and watch items weekly
   ```
   Expected output: a fill script plus a human habit. Success check: the script's numbers match a manual pull three weeks running.

4. Review it on a fixed cadence and keep the cadence. Weekly, same day, same readers. The habit is the dashboard; a perfect file nobody reviews on schedule is a diary.
   ```text
   review: every [day], readers: [names], timebox: 20 min
   ```
   Expected output: a calendar event with readers. Success check: three consecutive reviews happened on schedule.

5. Prune metrics that never drive decisions. If a headline has not influenced a decision in two months, demote it to an appendix or delete it. Dashboards accrete metrics; the prune is what keeps this one readable.
   ```text
   pruned this month: [metrics], reason: [one line each]
   ```
   Expected output: a shorter file over time. Success check: the headline count stays under ten.

## Variant phrasings
### Simple KPI tracking without a dashboard tool
Tool-skeptic phrasing. The whole skill: a file, version control, and a cadence beat tooling for small teams.

### Metrics in git
Version-control phrasing. Step 2 is the pitch: diffs of your metrics history are a superpower for postmortems.

### Weekly metrics file template
Template phrasing. Step 1's structure is the template; copy it and fill it.

### How to make founders actually read metrics
Audience phrasing. Short, same format every week, commentary in plain language; step 4's fixed cadence does the rest.

## Why it happens
Dashboards fail socially, not technically: they require someone to remember to open them, they show fifty numbers with equal weight, and they never say what changed or why it matters. A markdown file inverts all three: it arrives (via the cadence), it shows ten numbers, and the human-written section says what matters. Version control adds the history that dashboard tools charge extra for.

## Edge cases / pitfalls
- Do not commit secrets in the fill script. API keys and credentials live in the environment or a vault, never in the repo beside the metrics.
- Hand-editing numbers "to look better" will happen once under pressure; git history makes it visible, which is the point. Agree as a team that the file is write-once per week.
- If the team grows past the point where everyone fits in one review, graduate to real BI. This habit scales to about ten people, then it becomes a bottleneck.
- Charts are the one thing markdown does poorly. Link out to a chart image or accept sparklines in text; do not contort the format.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_FNZrtTgCIcF1y_Q-UNBkjA