Build and verify the report generator

Lesson outcome

You will have a working report generator on the VPS that reads a CSV and produces a formatted markdown report, verified against your success criteria.

Why this matters in an agency

This is the most complex thing you have built so far. It reads data, does calculations, formats output, and handles edge cases. And you built it by describing what you wanted in English. That is the entire thesis of this course in action. If you can build this, you can build client dashboards, automated emails, data processors, and content tools. The pattern is always the same: spec, build, verify.

Inputs, tools, and prerequisites

Claude Code running on the VPS. The report spec from the previous lesson (CSV format, output format, success criteria). The sample CSV file.

Step-by-step walkthrough

Give Claude Code the full spec

SSH into the VPS, navigate to your projects directory, and start Claude Code:

```
ssh vps
cd /root/projects
claude
```

Now give Claude Code the complete build instruction. Include everything from the spec:

```
Build a report generator script that does the following:

INPUT: A CSV file with columns: client_name, month, ad_spend, leads, conversions, revenue

OUTPUT: A markdown report file with:

• Title with the report period
• Summary section with totals: total spend, total leads, total conversions, average cost per lead across all clients
• One section per client with their individual metrics
• Month-over-month change percentages for each metric per client
• An analysis section that flags any client whose cost-per-lead increased more than 20% or whose conversions dropped more than 15%
• Professional language suitable for an account manager

The script should:

• Take the CSV file path as a command-line argument
• Output the report to stdout (so I can pipe it to a file)
• Handle missing data gracefully
• Be clear about what period it is reporting on

Save the script as report-generator.py (or .js — your choice) in the current directory.
```

Claude Code will write the script. This will take longer than previous scripts because it is more complex. Let it work.

Read the code before running

When Claude Code shows the file it wants to create, read through it. You do not need to understand every line, but look for the structural pieces:

• Does it read a CSV file? (Look for "csv" or "read" near the top.)
• Does it calculate totals? (Look for addition or summing.)
• Does it calculate percentages? (Look for division or "percent.")
• Does it format markdown? (Look for # characters or markdown formatting.)
• Does it take a command-line argument? (Look for "argv" or "args.")

If anything looks wrong or missing, ask Claude Code before approving:

```
Does this script handle the case where a client only has one month of data? How does it handle the month-over-month calculation in that case?
```

Run it against test data

Once the script is created, run it with the sample CSV:

```
Run the report generator on the sample CSV and show me the output.
```

Claude Code will execute the script and display the report. Read the report carefully.

Verify against success criteria

Go through your success criteria one by one:

1. Reads CSV without errors — Did the script run? Yes? Check.
2. Totals are correct — Add up the ad_spend column in the CSV manually (or ask Claude Code). Does the total in the report match? Check a few numbers.
3. Month-over-month calculations — Pick one client, calculate the change manually, compare to the report.
4. Flagged clients — Check the analysis section. Are the flagged clients actually the ones who meet the threshold? If a client's cost-per-lead went up 25%, it should be flagged. If it went up 10%, it should not be.
5. Clean markdown — Copy the output and paste it into a markdown preview tool (or create a note in your vault). Does it render cleanly?
6. Not hardcoded — Create a second CSV with different data. Run the report again. Does the output reflect the new data?

```
Create a second test CSV with different numbers and different client names. Then run the report generator on this new CSV.
```

If the report reflects the new data, the tool is working correctly — it is not hardcoded to the first dataset.

Fix issues

If any success criteria fail, tell Claude Code specifically what is wrong:

```
The month-over-month percentage for client "ABC Paving" is showing as -50% but when I calculate it manually it should be -33%. The calculation is wrong.
```

Claude Code will find the bug and fix it. Re-run and re-verify. This fix cycle is normal and expected.

Save the report to a file

Once the tool is verified, generate a real report and save it:

```
Run the report generator on the sample data and save the output to /root/vault/Reports/March-2026-Performance-Report.md
```

Create a Reports folder in your vault if it does not exist. The report is now a vault note — viewable in Obsidian and accessible to Claude Code for future reference.

Failure modes and verification checks

The main failure is not verifying. If you run the script and say "looks good" without checking the numbers, you have a tool that may produce wrong outputs. The second failure is giving up when the first run has errors. Every first build has issues. The fix cycle is where the tool becomes reliable.

Verification: all six success criteria pass. The tool produces correct output on two different datasets. A report exists in your vault.

Implementation checklist

• Give Claude Code the full spec as a single prompt.
• Read the generated code and ask questions about anything unclear.
• Run the script on the sample CSV.
• Verify all six success criteria.
• Fix any issues found and re-verify.
• Run on a second dataset to confirm it is not hardcoded.
• Save a report to the vault.

Immediate next action

Move to the next module. You have a working tool on the VPS. Now you will write the CLAUDE.md that makes Claude Code aware of your entire setup — vault structure, operating rules, and tool locations — so it gets smarter in every conversation.

Exercise

Modify the report generator to produce something slightly different. Choose one:

```
Add a "Recommendations" section to the report that suggests specific actions for any flagged clients. For example, if a client's cost-per-lead spiked, suggest reviewing ad targeting or pausing underperforming campaigns.
```

Or:

```
Add a chart section that shows a simple ASCII bar chart comparing each client's cost-per-lead side by side.
```

Run the modified report, verify the new section is there and makes sense. You are now iterating on your own tool — the same build-verify-improve loop that professional software developers use, but you are doing it in English.