LEARNING OUTCOMES
Leave evidence another person can follow.
By the end of the lesson, you should be able to render a small notebook, rerun it from a clean session, document the data, and disclose how an AI agent contributed.
- 01Organize code in a readable sequence from input to output.
- 02Render a Quarto notebook with code, results, and interpretation.
- 03Run the project from a clean R session.
- 04Write a concise source, limitation, and AI-use note.
- 05Audit someone else’s handoff constructively.
Why this matters for policy work
Policy analysis rarely remains on the computer where it began. A colleague may need to update the data, a decision maker may ask where a number came from, or a future analyst may have to reproduce the figure after the original author has moved on. A handoff is successful when that person can reconstruct the path from question to source to code to claim without relying on private memory.
A recipe has not been tested because its author can cook the dish from memory. It is tested when another person, with the listed ingredients and equipment, can follow the written sequence and obtain the expected result. A clean project run removes the analyst's remembered objects, console history, local paths, and silent explanations in the same way.
Agent-assisted work makes disclosure part of that path. Saying that AI was used is not enough. A useful record distinguishes what the agent generated, which files or sources it consulted, what the analyst checked, and which uncertainty remains. This is not paperwork added after analysis. It is how responsibility stays visible when computational work is shared.
MINIMUM HANDOFF
Small, complete, optional.
| Element | Minimum | Question to ask |
|---|---|---|
| Question | One descriptive or associational question. | Can a reader identify the population and outcome? |
| Data | Source, years, unit, and indicator definitions. | Could the file be rebuilt? |
| Code | One R script or Quarto notebook. | Does it run from a clean session? |
| Evidence | One figure or table and one careful statement. | Does the statement match the output? |
| Disclosure | What the agent did and what the human verified. | Is responsibility visible? |
Not an assignment. Nothing is graded or submitted. The artifact is a personal field notebook that can travel into the fall semester if it is useful.
COLD-RUN TEST
Reproducibility begins when memory is removed.
Code can appear to work because objects, packages, or manual edits remain in the current session. A clean render starts without those invisible supports and reveals what the project actually contains.
| Hidden dependency | Symptom | Repair |
|---|---|---|
| Console-created object | object not found after restart. | Create it in the script before use. |
| Unloaded package | A function works only in the old session. | Load the package explicitly near setup. |
| Absolute path | The file works only on one computer. | Use a project-relative path. |
| Manual data edit | The output cannot be rebuilt from source. | Express the change in code and preserve raw data. |
| Stale output | The figure disagrees with current code. | Render outputs from the current source. |
Live failure clinic
The instructor will open a notebook that appears complete but fails from a clean session. Students first predict the hidden dependency, then propose the smallest repair, then verify by rendering again. The failure is the lesson evidence, not an interruption.
LIVE CODING
Turn working code into a readable trail.
Inputs, setup, transformations, analysis, and outputs.
Add question, definitions, interpretation, and limitation.
Build the notebook and repair hidden-state failures.
Describe agent contributions and human checks.
Run the four-part audit before the lab exchange.
---
title: "Math Camp field notebook"
format: html
execute:
echo: true
warning: false
---
## Question
## Data and definitions
## Comparison
## What this does not show
## AI-use noteThe YAML header gives Quarto the document title and output format. Keeping echo: true makes the code visible in the rendered notebook, while warning: false suppresses routine warnings without hiding errors.
Question and data come before results so a reader can recover the population, variables, years, source, and definitions before encountering a figure or table.
Comparison and limitation keep the numerical result beside the sentence it can support and the stronger claim it cannot establish.
The AI-use note records what the agent contributed, which context it read, what the analyst verified, and any unresolved uncertainty. A clean render then tests whether this trail depends on forgotten console commands or local state.
FOUR-PART AUDIT
Use the harness to make review observable.
An audit is more trustworthy when it leaves a trail. Ask the agent to cite exact files, run named checks where permitted, and separate observed failures from recommendations. The harness can expose tool calls and command output; the human reviewer still decides whether those checks address the policy and statistical risks that matter.
Goal: Audit this project for handoff readiness. Context: Read the README, data documentation, R or Quarto source, and rendered output. Review separately: (1) reproducibility, (2) data provenance and integrity, (3) statistical interpretation, and (4) communication and accessibility. Constraints: Do not edit files. Rank issues by consequence. Cite the file and evidence for every claim. Say when you are uncertain. Done when: I have a short prioritized checklist that a human can verify.
| Audit evidence | What it proves | What it does not prove |
|---|---|---|
| Clean render log | The documented path executed in this environment. | The statistical claim is appropriate. |
| Key and range checks | Named structural conditions held. | The indicator measures the intended concept. |
| Diff or change summary | Which source files changed. | The changes improved the analysis. |
| AI-use note | How assistance and verification were described. | That every generated contribution was correct. |
- □Does the project run after restarting R?
- □Are data source, retrieval date, and indicator definitions present?
- □Does the text avoid unsupported causal language?
- □Does the AI-use note distinguish generation from verification?
SLIDES
Lesson deck.
Edit the source deck freely, then render it back to this stable location.