# How we auto-generate the weekly metrics report

The reporting agent we run on Kortix — connected to our Postgres database and Slack. Every Monday it queries the metrics, writes the report with commentary on what moved, and posts it.

Canonical page: https://openchatly.com/use-cases/weekly-report

Every team has a weekly metrics report, and someone spends part of their Monday
building it: running the same queries, dropping the numbers into a template, and
writing a line or two about what changed. It's routine, it's on a schedule, and
it's exactly the kind of thing that gets skipped the week it's most needed.

We run a reporting agent on Kortix that builds it. A Monday cron queries the
metrics from our Postgres database, writes the weekly report with commentary on
what moved and why, and posts it to Slack. Access to the database is read-only.
This write-up covers how the setup works: the trigger, the session model, and the
guardrails.

- **Team:** Kortix
- **Runs on:** A Monday cron
- **Connected systems:** Postgres · Slack
- **Mode:** Cron-driven · read-only database access

## The problem

The weekly report is low-skill, high-consistency work: the same queries, the same
layout, every week. Done by hand it eats an hour of someone's Monday, and the week
things are busiest is the week it's most likely to slip — which is usually the
week the numbers most needed a look.

The common fixes are incomplete. A static dashboard shows the numbers but doesn't
say what moved or why, so someone still has to read it and write the summary. A
scheduled SQL job can post the figures but not the commentary. The interpretation
— what changed, whether it matters — is the part that takes a person, and it's the
part that gets dropped.

## What we built

On Kortix, a Monday cron triggers a reporting agent. Each run spawns an isolated
session (a cloud sandbox) with scoped, read-only access to the Postgres database
and permission to post to one Slack channel. The agent runs the metric queries,
compares them against the prior weeks, writes commentary on what moved, and posts
the report to Slack. It cannot write to the database.

## How it works

### Copy the setup prompt into a new session

Open your Kortix workspace, start a new session, paste this prompt and send it.
The agent writes the agent file, the report skill and the weekly trigger, and opens a change request for you to review. Prefer
clicks? Choose **Use this template** instead.

**Setup prompt**

```
Set up a weekly metrics report agent in this workspace.

1. Create the agent agents/weekly-report.md. Its job is to build the weekly metrics report from Postgres and post it to Slack. It may use the PostgreSQL connector, read-only.

2. Create the skill skills/weekly-metrics-report/SKILL.md with these rules:
   - Report exactly the metrics defined in memory/weekly-report.md. If a definition is missing, state the assumption in the report.
   - Query this week from Monday 00:00 and the prior 4 weeks for comparison, with SELECT only.
   - A move is notable at 15% or more week over week, or when it breaks a trend of 3 or more weeks.
   - Write one or two plain sentences for each notable move. Steady metrics get the number only.
   - Report missing data as a gap. Never fill it with a guess.
   - Post exactly one report to #metrics: the date range, the numbers with deltas, the commentary and any data notes.

3. Add a cron trigger weekly-metrics-report to kortix.yaml. It runs the weekly-report agent every Monday at 06:00 with the prompt "Load the weekly-metrics-report skill and post this week's metrics report to #metrics."

4. Tell me which of these connectors are not connected yet.

5. Open a change request with all of it. Do not merge it.
```

### Connect your tools

Open **Connectors** in your workspace and connect your database with a role that
can only select, and Slack for the report. Credentials are brokered server-side
and never enter the agent's machine.

- **PostgreSQL** (Required):
Queries the metrics tables, read-only.
- **Slack** (Required):
Posts the weekly report with commentary on what moved.

### Run it once with this prompt

Merge the change request, then start a session with the **weekly-report** agent
and send this prompt. Check the numbers against your own dashboard before you
let the schedule take over.

**Prompt**

```
Build this week's metrics report.

1. Query this week's metrics from Postgres through the read-only role.
2. Query the same metrics for the prior 4 weeks.
3. Compute the week-over-week change and flag moves of 15% or more.
4. Write one or two sentences on each notable move, and report any missing data as a gap.
5. Post one report to #metrics.
```

### Let the weekly schedule take over

The change request added this trigger to `kortix.yaml`. From now on the agent
runs every Monday at 06:00, each run in a new session on its own cloud computer.
To change the time, edit the cron line, or open **Triggers** in the workspace.

**kortix.yaml**

```yaml
triggers:
  - slug: weekly-metrics-report
    name: Weekly metrics report
    on:
      cron: "0 0 6 * * 1"
    run:
      agent: weekly-report
      prompt: Load the weekly-metrics-report skill and post this week's metrics report to #metrics.
```

### Keep the database read-only

The Postgres role can run SELECT and nothing else, and it reaches only the
metrics tables. The report cannot change the data it reports on. The Slack post
is the only output, and the team decides what to do about each move.

### Read the weekly report

Each run ends with one message in #metrics. This is what a run looks like
in the session:

> **Weekly metrics report · Mon 06:00**
>
> Prompt: Load the weekly-metrics-report skill and post this week's metrics report to #metrics.
>
> Posted the report for **12** metrics. **2** moves are notable: signups rose
> **18%** week over week, and trial conversion fell to **9.4%**, below its
> 4-week average. **1** metric had no data for Sunday.

> **The pattern**
> A Monday **trigger** spawns a session with scoped **connectors**: a read-only
> role into Postgres and a single Slack channel out. The report playbook is encoded
> as **skills** and **memory**. The agent queries, interprets, and posts — with no
> path to write to the database.

## Make it do more

Once it works, paste any of these into the same session.

**Add a chart**

```
Attach a line chart of each notable metric over the last 8 weeks to the report.
```

**Explain a big move**

```
When a metric moves 15% or more, break it down by plan and add the biggest driver to the commentary.
```

**Monthly rollup**

```
On the first Monday of each month, add a section that compares last month to the month before.
```

## Guardrails

The agent reads production data, so the access is scoped and contained:

- **Isolation.** Every run happens in its own isolated sandbox. The session queries
  the metrics and drafts the report; only the Slack message is written back out.
- **Scoped secrets.** The Postgres and Slack credentials are encrypted in the
  secrets manager and injected into the sandbox at runtime, scoped to the agents you grant them to.
- **Read-only database access.** The database role can select and nothing else —
  no insert, update, or delete — and it's scoped to the metrics tables. The report
  cannot change the data it reports on.
- **Everything is code.** The agent's configuration, skills, and permissions are
  files in the repo, versioned and changed through a reviewed **change request**
  rather than a dashboard setting.

## The outcome

- **Every Monday:** The report built and posted before the team logs on
- **With commentary:** What moved and whether it matters, not just numbers
- **Read-only:** Production metrics queried, never written

The weekly report stops depending on someone having a free Monday, and it arrives
with a read of what changed rather than a table to interpret. The team starts the
week looking at the movement that matters instead of assembling the numbers by
hand.
