Define the report generator

Lesson outcome

You will have a clear specification for a report generator that Claude Code can build — what it reads, what it produces, and how you will know it works.

Why this matters in an agency

Every agency produces reports. For clients, for internal review, for sales conversations. Most agencies do this manually — pulling numbers from dashboards, pasting them into a template, formatting, writing a narrative. A report generator automates the first 80%. It pulls data, formats it, and produces a draft. You review and send. That turns a 45-minute task into a 5-minute task.

Building this tool also teaches the most important lesson in operator work: scope before you build. Jumping straight to "build me a report tool" produces vague, unfocused output. Defining the spec first — what goes in, what comes out, what "correct" looks like — produces something you can actually use.

Inputs, tools, and prerequisites

Claude Code running on the VPS. Your vault with business notes from Module 10. A clear idea of what kind of report your agency produces most often.

Step-by-step walkthrough

Choose the report type

Pick the report you produce most frequently. Common options for agency owners:

• Client performance report — metrics like leads, spend, cost-per-lead, conversions
• Weekly status report — what was done, what is next, what is blocked
• Content calendar summary — what content is planned, published, and pending
• Sales pipeline report — active leads, stage, expected close dates

Pick one. For this walkthrough, we will use a client performance report, but the process is identical for any type.

Define the data source

Your report needs data to report on. For this first tool, you will use a CSV file as the data source. This keeps things simple — no database connections, no API integrations. You put numbers in a spreadsheet, export it as CSV, and the tool reads it.

Ask Claude Code to help you define the format:

```
I want to build a report generator that reads client performance data from a CSV file and produces a formatted markdown report. The CSV should have these columns: client_name, month, ad_spend, leads, conversions, revenue. Help me create a sample CSV with realistic test data for 3 clients over 2 months.
```

Review the sample CSV Claude Code creates. Does it match the metrics your agency actually tracks? If not, modify the columns. This is your spec — the data format the tool will expect.

Define the output format

Now describe what the report should look like:

```
The report should be a markdown file with:

• A title with the report month
• A summary section with totals across all clients (total spend, total leads, total conversions, average cost per lead)
• A section per client showing their individual metrics and month-over-month change percentages
• A brief analysis section that flags any client whose cost-per-lead increased more than 20% or whose conversions dropped more than 15%
• The report should be written in professional language suitable for sending to an agency owner or account manager
  ```

Write this description down (or save it in a vault note). This is your output spec.

Define success criteria

Before building anything, define how you will know it works:

1. The tool reads the CSV without errors.
2. All totals and averages are mathematically correct.
3. The month-over-month calculations are correct.
4. Flagged clients actually meet the threshold criteria.
5. The output is clean, readable markdown.
6. Running the tool on different CSV data produces a different report (it is not hardcoded).

These criteria turn "does it work?" from a vague feeling into a checkable list.

Failure modes and verification checks

The failure mode here is not building anything — it is building without a spec. If you skip this lesson and jump to "build me a report tool," you will spend more time reworking the output than you would have spent writing the spec.

Verification: you have a sample CSV, an output format description, and a list of success criteria. All three exist as notes or files before you write any code.

Implementation checklist

• Choose the report type you produce most often.
• Define the CSV column format with Claude Code.
• Create a sample CSV with realistic test data.
• Write the output format description.
• Define 5-6 success criteria.
• Save everything in the vault or in files on the VPS.

Immediate next action

Move to the next lesson and build the report generator.

Exercise

Before moving on, ask Claude Code:

```
Based on the report spec I just defined, what could go wrong when we build this? What edge cases should we handle?
```

Read the response. Claude Code will mention things like: missing CSV data, division by zero for cost-per-lead calculations, clients with only one month of data (no month-over-month comparison possible), and malformed CSV files. You do not need to solve all of these now. But knowing the edge cases before you build is part of scoping well.