5 A First Report, by Hand
Quarto, reproducible publishing, coding agents, Markdown, Python, EPUB, data analysis, k-means clustering
Somewhere in this chapter’s report is a wrong number. The report renders without a single error, reads perfectly well and cites its source, and one of its figures is out by 360,000 visits. Finding it takes no programming, only a habit: put each number beside the data it came from.
That habit is the Check in this book’s title, and this chapter is where you practise it with your own hands. You type every command yourself, at the terminal, on a real report: copy it, render it, check it, record it with Git, change it and undo the change, break it three ways on purpose and read the errors. Only at the end does the agent make an edit, and you check its work with the same commands you have just learned. Allow about 45 minutes; less if the terminal is already familiar.
- Copy a project, move into it and render it from the terminal.
- Check every number in a report against its data, and trace a wrong one to where it was typed.
- Record, compare and undo changes with
git status,git diff,git restoreandgit commit. - Read an error from its first line, and check an agent’s change before you commit it.
5.1 Get the files
Step 5 of Chapter 4 cloned the workshop’s files into ~/quarto-workshop. Among them is a small report, starters/first-report. Copy it out, so that the original stays as it was. Type it with Tab completion, which saves typing and catches mistakes: type cp -R ~/quarto-workshop/st and press Tab, and the terminal finishes the name, starters/. When several names fit, press Tab again to list them. When Tab does nothing at all, no name starting that way exists there, which is worth knowing before you press Enter. In the terminal, in any folder:
cp -R ~/quarto-workshop/starters/first-report ~/first-reportcp copies, and -R (recursive) copies a folder with everything inside it. It prints nothing. Many commands work this way: cp, cd and, later, git add say nothing when they succeed, and speak only when something is wrong. In the terminal, silence is success.
If cp says No such file or directory, your copy of the workshop is older than this chapter: cd ~/quarto-workshop, then git pull, then run the cp line again.
Now move into the copy and look around. In the terminal:
cd ~/first-report
pwd
lspwd prints the folder you are in, ending in first-report (/home/ana/first-report on Linux, /Users/ana/first-report on a Mac, with your own name). ls lists six names, in an order that depends on your system:
| Name | Holds |
|---|---|
report.qmd |
the report’s source: settings, one code cell and its sentences |
data/ |
visits.csv, the data the report reads |
AGENTS.md |
the project’s rules for the agent (Section 2.5) |
README.md |
what the folder is, in a few lines |
pyproject.toml, uv.lock |
the Python packages the report needs, with exact versions |
A name with a space
The terminal splits what you type at each space, so a folder name with a space in it needs care. Try it once, from your home folder. In the terminal:
cd ~
mkdir "my reports"
cd my reportscd complains, in words that depend on your shell:
bash: cd: too many arguments (Ubuntu)
cd: string not in pwd: my (Mac)
cd was given two names, my and reports. Keep the name in one piece with quotes, cd "my reports", or with a backslash before the space, cd my\ reports. Tab completion types the backslash for you: type cd my and press Tab. Then tidy up and go back:
cd ~
rmdir "my reports"
cd ~/first-reportThe folders in this book have no spaces in their names, and yours need not either: a hyphen, as in first-report, does the same job.
5.2 Render it yourself
In the terminal, in ~/first-report:
uv run quarto render report.qmduv run runs a command in the project’s own Python environment (Section 1.4; Section 6.10 has more). The first time, it builds that environment from uv.lock, which takes from a few seconds to a minute, and may print some Downloading lines first. Then Quarto renders, and prints a good deal (trimmed here where marked …):
Using CPython 3.12.13
Creating virtual environment at: .venv
Installed 39 packages in 301ms
Starting python3 kernel...[IPKernelApp] WARNING | …
Done
Executing 'report.quarto_ipynb'
Cell 1/1: ''...Done
pandoc
to: html
output-file: report.html
…
Output created: report.html
When a render succeeds, its last line is Output created: report.html. The lines after pandoc are its settings, and the IPKernelApp warning is harmless (Section 4.7). Your Python version, package count and timings may differ.
Open the page. In the terminal, run open report.html (Mac), xdg-open report.html (Linux), or explorer.exe . and then double-click report.html (Windows, in Ubuntu). The browser shows:
Five London Sights
Five of London’s best-known sights had 25,036,711 visits between them in 2025. The most visited was the Natural History Museum (South Kensington), with 7,116,929, and 4 of the five are free to enter.
Tate Modern, on the South Bank, had 4,154,266 visits.
Source: ALVA, “Visits made in 2025 to visitor attractions in membership with ALVA” (only ALVA member attractions are counted).
Now open the folder itself: open . (Mac), xdg-open . (Linux) or explorer.exe . (Windows, in Ubuntu), where . means “this folder”. The file browser shows the same files as ls, plus the new ones the render made: report.html and report_files/. The terminal and the file browser are two views of one folder.
5.3 Check every number against the data
The render worked. That proves the code ran, not that the report is right. Look at the data. In the terminal, in ~/first-report:
cat data/visits.csvcat prints a file. A CSV is a table in plain text, with commas between the columns. This one has a first line naming its seven columns, then five rows, one for each sight. Each row carries its source, url and retrieved date, so the lines are long and wrap. Ask for just the first two columns:
cut -d, -f1,2 data/visits.csvcut keeps some columns of each line: -d, says the columns are separated by commas, and -f1,2 keeps the first and second. It splits at every comma, even one inside quotes, so it is safe here only because the first two columns hold no commas.
attraction,visits_2025
Natural History Museum (South Kensington),7116929
The British Museum,6440120
Tate Modern,4514266
National Gallery,4147544
Tower of London,2817852
Put the page beside this list. Which of the page’s numbers does not match a row? (The total is the sum of the five; a calculator will confirm it, but you need not.)
Tate Modern’s. The page says 4,154,266; its row says 4514266: two digits swapped. Nothing warned you, because Quarto rendered the sentence faithfully: to Quarto it is just words. To fix it, find where that number came from.
The report’s source says where each number comes from. In the terminal:
cat report.qmd---
title: "Five London Sights"
format: html
---
```{python}
#| echo: false
import csv
with open("data/visits.csv") as f:
rows = list(csv.DictReader(f))
total = sum(int(r["visits_2025"]) for r in rows)
top = max(rows, key=lambda r: int(r["visits_2025"]))
free = [r for r in rows if r["admission"].startswith("Free")]
```
Five of London's best-known sights had `{python} f"{total:,}"` visits
between them in 2025. The most visited was the `{python} top["attraction"]`,
with `{python} f"{int(top['visits_2025']):,}"`, and `{python} len(free)` of
the five are free to enter.
Tate Modern, on the South Bank, had 4,154,266 visits.
Source: ALVA, "Visits made in 2025 to visitor attractions in membership with
ALVA" (only ALVA member attractions are counted).
You met these parts in Section 1.2: the settings between the --- lines, a code cell that reads data/visits.csv and computes total, top and free, and inline code, the `{python} …` pieces, which Quarto replaces with computed values. Chapter 7 explains every line. For now, notice what is computed and what is not. Every other number on the page is inline code that reads the data; that sentence was typed.
A typed number is a copy, made once by a person, and nothing connects it to the data afterwards. Swapped digits are the classic copying slip, but the deeper problem is what happens next: when the data change, the copy stays as it was. That is the drift of Section 1.1, and Section 5.5 lets you watch it happen.
5.4 Start a history
Before you change anything, record the report as it is, so that you can always get back to it. Git, which you installed in Chapter 4, does this (Section 1.4). In the terminal, in ~/first-report:
git init -b mainInitialized empty Git repository in /home/ana/first-report/.git/
The folder is now a repository: it has a hidden .git folder where Git keeps the history. -b main names the repository’s first branch, its line of history, main, as GitHub does. (This needs Git 2.28 or newer; git --version shows yours, and the setup in Chapter 4 installs a newer one.) Ask Git what it sees:
git statusOn branch main
No commits yet
Untracked files:
(use "git add <file>..." to include in what will be committed)
.gitignore
AGENTS.md
README.md
data/
pyproject.toml
report.qmd
uv.lock
nothing added to commit but untracked files present (use "git add" to track)
Untracked files are ones Git can see but does not yet record. Three things in the folder are missing from the list: .venv/, report.html and report_files/. They are left out by .gitignore, a file that lists what Git should ignore; ls hides it because its name starts with a dot, and ls -a shows it. It names everything that uv and the render rebuild, so the history holds only the sources.
Record everything else as the first commit, a saved state with a message saying why:
git add .
git commit -m "Starter report, as copied"git add . prints nothing: it chooses what goes into the next commit, and . means “this folder”, everything not ignored. git commit records it:
[main (root-commit) 15856fe] Starter report, as copied
7 files changed, 916 insertions(+)
create mode 100644 .gitignore
…
The seven characters after root-commit name the commit; yours will differ. Check again:
git status
git log --onelineOn branch main
nothing to commit, working tree clean
15856fe (HEAD -> main) Starter report, as copied
The working tree is the files in the folder as they are now; “clean” means they are exactly as the last commit recorded them. git log --oneline lists the commits, newest first, and (HEAD -> main) marks the commit your files are at now.
If git commit says “Author identity unknown”, Git does not know your name yet (Step 5 of Chapter 4 sets it). Run the two git config --global lines it prints, with your own name and email, then commit again. If you leave out -m "…", Git opens an editor for the message: leave it without saving (in nano, Ctrl+X; in Vim, Esc, then :q! and Enter) and run the command again with -m.
5.5 Predict, change, rebuild
Suppose ALVA corrects Tate Modern’s figure upwards by 1,000,000. Make that change to the data yourself, with nano, the terminal’s own small text editor. In the terminal, in ~/first-report:
nano data/visits.csvPress the down arrow three times to reach the Tate Modern row; its long line runs off the right edge of the window, which is fine. Press the right arrow until the cursor is just after the first digit of 4514266, press Backspace to delete the 4, and type 5, so that the number reads 5514266. Save with Ctrl+O, then Enter; leave with Ctrl+X.
In nano, Ctrl+O (“write Out”) asks for the file name: press Enter to keep it. Ctrl+X leaves; if you have not saved, nano asks first: Y then Enter saves, N throws the changes away. The keys are listed along the bottom of the screen, where ^ means Ctrl. On a Mac, nano opens Pico, which uses the same keys (checked on macOS 26, 2026-11-12).
Before you render, ask Git what you changed:
git status
git diffIf the diff is longer than the window, Git shows it a screen at a time, with : or (END) on the last line: press Space for more and q to get your prompt back. Removed lines are red and added lines green.
On branch main
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git restore <file>..." to discard changes in working directory)
modified: data/visits.csv
no changes added to commit (use "git add" and/or "git commit -a")
A diff is the lines a change removed and added. The real lines are long, so here each is cut short where you see …:
diff --git a/data/visits.csv b/data/visits.csv
index eb394b9..8c1eea7 100644
--- a/data/visits.csv
+++ b/data/visits.csv
@@ -1,6 +1,6 @@
attraction,visits_2025,admission,note,s…
Natural History Museum (South Kensingto…
The British Museum,6440120,Free (paid e…
-Tate Modern,4514266,Free (paid exhibiti…
+Tate Modern,5514266,Free (paid exhibiti…
National Gallery,4147544,Free (paid exh…
Tower of London,2817852,Paid,,"ALVA, Vi…
Read it from the top. --- is the file before, +++ after, and @@ … @@ says which lines follow. A line starting - was removed, a line starting + was added, and a line starting with a space is unchanged context. One line changed, in one file: exactly the edit you meant.
Before you render: of the report’s four numbers (the total, the most visited sight’s count, the free count and Tate Modern’s), which will change?
Only the total, which rises by 1,000,000 to 26,036,711. The Natural History Museum (South Kensington) is still the most visited, the free count is still 4, and the Tate Modern sentence still says 4,154,266. It was typed, so it cannot follow the data, not even when the data change in the very row it describes.
Now rebuild and look. In the terminal:
uv run quarto render report.qmdReload report.html in the browser (it does not reload itself). The total now reads 26,036,711, and the Tate Modern sentence has not moved. That is Section 1.1 on your own screen: one input changed, the computed numbers followed it, and the typed one was left behind.
The trial value is not real, so undo it:
git restore data/visits.csv
git statusOn branch main
nothing to commit, working tree clean
git restore puts a file back as it was at the last commit. It is the undo for any file Git tracks, and it is final: the change it discards was never recorded, so it is gone. Render once more, and the page is back to 25,036,711.
5.6 Three mistakes on purpose
Errors are messages, not verdicts, and they are easiest to learn from when you caused them on purpose. For each mistake below, make it, read the message, and check one piece of evidence before you fix anything. Three rules for reading an error:
- Find the first line that says
ERRORorerror, often in red: it says what went wrong. When a long stack trace follows, scroll up to it. - Look where the caret
^points, when there is one: that is where the program noticed. - Skip the stack trace. Many Quarto errors end with
Stack trace:and a list of lines startingat …, eight for a wrong folder and more than twenty for broken settings. A stack trace lists what was running inside Quarto when it stopped: it is for Quarto’s developers, not for you.
The wrong folder
In the terminal:
cd ~
uv run quarto render report.qmdERROR: No valid input files passed to render
Stack trace:
at _Command.actionHandler (file:///…/quarto.js:142967:11)
…
Quarto found no file to render. Before you change anything, what do you check?
Where you are, and what is there: pwd prints your home folder, and ls shows no report.qmd. The command was right and the folder was wrong. A misspelt name, such as reprot.qmd, gives the same message, and ls shows that too. Fix it with cd ~/first-report, then render again: the last line is Output created: report.html.
A typo in the command
In the terminal, in ~/first-report:
uv run quatro render report.qmderror: Failed to spawn: `quatro`
Caused by: No such file or directory (os error 2)
What does the first line tell you, and what is the fix?
uv could not start a program called quatro, because there is none. The error quotes the name back: compare it, letter by letter, with what you meant. Press the up arrow to bring the command back, correct it, and press Enter. Without uv run, the shell says the same thing in its own words: zsh: command not found: quatro on a Mac, quatro: command not found on Ubuntu.
Broken settings
Open report.qmd with nano report.qmd, delete the space after the colon in format: html so that it reads format:html, save and leave. Then, in the terminal:
uv run quarto render report.qmdERROR: YAMLException: can not read a block mapping
entry; a multiline key may not be an implicit key (4:1)
1 |
2 | title: "Five London Sights"
3 | format:html
4 |
-----^
Stack trace:
at …
(The first line is one line on your screen, split here to fit; the stack trace runs to more than twenty lines.)
The caret points at line 4, which is empty. Where is the mistake, and how do you check?
On line 3, the line above. (4:1) means line 4, column 1, counted inside the settings block, where line 1 is the opening --- and shows as empty. Without the space, format:html is not a setting, so YAML, the format of those settings, reads on and gives up at line 4. Look at the caret’s line and the line above it. git diff shows the one line you changed.
Fix it by putting the space back, or with the general undo, git restore report.qmd. Then render again to confirm: the last line is Output created: report.html.
5.7 Hand the fix to the agent
You know where the bug is, you can see any change with git diff, and you can undo one with git restore. That is the moment to delegate: not before you can check the work, but as soon as you can. Start your agent in the report’s folder. In the terminal:
cd ~/first-report
claudeType codex or agy in place of claude if that is your agent. Trust the folder when it asks, because you made it (in Claude Code, press the down arrow first: the choice starts on No). (Codex asks here, and not in ~/setup, because this folder is now a Git repository.) Then, at the agent’s prompt:
In report.qmd, the sentence about "Tate Modern" types its visit count by hand. Replace the typed number with inline code that reads Tate Modern's `visits_2025` from data/visits.csv. Do not change data/visits.csv. Render with `uv run quarto render report.qmd` and tell me the number the sentence now shows.reads AGENTS.md, report.qmd and data/visits.csv · edits report.qmd · uv run quarto render report.qmd
approve its commands · /exit · then, in the terminal, git status and git diff
The starter’s AGENTS.md already says that data/visits.csv must never be edited and that every number comes from the data through inline code, so the agent is likely to get this right. Likely is not checked.
The agent reports: “Done. The sentence now shows the figure from the data.” Why run git diff anyway?
The agent’s message is a claim about the files; the diff shows the files themselves, every file and line that changed, including any the agent did not mention, such as an edit to the data.
5.7.1 Three checks for every change
Every change in this book, yours or the agent’s, passes the same three checks: two before you commit it, and one after. Here they are, applied to this one:
| Check | Asks | Here |
|---|---|---|
| Scope | Did only the files I meant change? | git status lists report.qmd alone; git diff shows the lines |
| Correctness | Does one number match its source row? | the page’s Tate Modern figure against its row in cut -d, -f1,2 data/visits.csv |
| Rebuild | Does what you committed build on its own? | render a fresh clone of the repository (below) |
Scope. git status should list one modified file, report.qmd. If data/visits.csv is listed too, the agent broke the project’s rule: git restore data/visits.csv undoes that part. The diff will look something like this one, from a version written by hand to test the step (trimmed at the …); an agent’s will differ in detail:
diff --git a/report.qmd b/report.qmd
index 4147a02..39b9454 100644
--- a/report.qmd
+++ b/report.qmd
@@ -13,6 +13,8 @@ with open("data/visits.csv…
total = sum(int(r["visits_2025"]) for r in …
top = max(rows, key=lambda r: int(r["visits…
free = [r for r in rows if r["admission"].s…
+tate = next(int(r["visits_2025"]) for r in rows
+ if r["attraction"] == "Tate Modern")
```
Five of London's best-known sights had `{py…
@@ -20,7 +22,7 @@ between them in 2025. The …
with `{python} f"{int(top['visits_2025']):,…
the five are free to enter.
-Tate Modern, on the South Bank, had 4,154,266 visits.
+Tate Modern, on the South Bank, had `{python} f"{tate:,}"` visits.
Source: ALVA, "Visits made in 2025 to visit…
ALVA" (only ALVA member attractions are cou…
The typed number has gone, and in its place is inline code that looks Tate Modern up in the data.
Correctness. Reload report.html: the sentence should now say 4,514,266, which is 4514266 in the Tate Modern row of the cut output in Section 5.3.
If either check fails, git restore report.qmd puts the file back as it was before the agent touched it, and you can ask again. Undo works on the agent’s changes exactly as on yours.
When both pass, commit, in the terminal:
git commit -am "Compute Tate Modern's visits from the data"
git log --oneline-a adds every tracked file that changed, so you need no git add; -m gives the message. Your hash, and perhaps the count of lines, will differ:
[main d7e7f02] Compute Tate Modern's visits from the data
1 file changed, 3 insertions(+), 1 deletion(-)
d7e7f02 (HEAD -> main) Compute Tate Modern's visits from the data
15856fe Starter report, as copied
Rebuild. The last check asks whether everything the report needs is in the history, and not only in your folder. Clone the repository into /tmp, a folder for temporary files, which the computer empties from time to time, and render the clone. In the terminal:
git clone ~/first-report /tmp/first-report-check
cd /tmp/first-report-check
uv run quarto render report.qmdCloning into '/tmp/first-report-check'...
done.
The clone has no .venv/ and no report.html, because .gitignore kept them out of the history, so the render prints Creating virtual environment again and then builds the page. (If Git says the destination already exists, you have run this before: pick another name, such as /tmp/first-report-check2.) Open the clone’s page as you opened yours: open report.html (Mac), xdg-open report.html (Linux), or explorer.exe . and then double-click report.html (Windows, in Ubuntu). It should match yours, 4,514,266 and all. If the clone does not render, something the report needs was never committed: add it and commit again. Then cd ~/first-report to go back; the clone is disposable.
Summary
- A report that renders without an error can still be wrong: put each number beside its row in the data, and trace a wrong one to where it was typed.
- Typed numbers drift and computed ones follow the data. Change one input, predict, rebuild and explain.
git statussays what changed,git diffshows how,git restoreundoes it andgit commitrecords a state you can return to.- Read an error from its first line and the caret, skip the stack trace, and check one piece of evidence (
pwd,ls,git diff) before you fix anything. - Delegate a change once you can check it: scope, correctness and rebuild (Table 5.2), then commit.
You have now made, by hand, every check the rest of the book asks you to make of an agent’s work, on a project small enough to see whole. Part II scales it up. Each project starts as this one did, with git init, so every agent edit in it can be seen with git diff and undone with git restore. Chapter 6 starts the London guide from an empty folder and explains, one construct at a time, the Markdown you have just been reading.
Further reading
- Scott Chacon and Ben Straub, Pro Git, Recording Changes to the Repository and Undoing Things, which covers
git restore(checked 2026-11-17). - Git,
git initandgit restorereference pages (checked 2026-11-17). - GNU nano, cheat sheet of its keys (checked 2026-11-17).
- Astral, Running commands with
uv run(checked 2026-11-17).