Collaboration and replication

Today

• You work with one classmate. The class forms three pairs.
• You work in your partner’s project while your partner works in yours.
• Today’s topics:
  • giving your partner your project files and getting their changes back,
  • reading your partner’s website and repository and giving written feedback,
  • rerunning your partner’s analysis to see whether you get the same results (replication),
  • doing one small task in your partner’s project from their written instructions.
• You report what you found in your Week 12 final presentation.

Ways to share a project

• Your partner needs your files on their computer.
• You need their changes back in your project.
• There are three common ways to do this:
  • sending a copy, as a zip file or an email attachment,
  • a shared cloud folder, such as Dropbox, Google Drive, or OneDrive,
  • GitHub.

• Choose the method with your partner.
• Each of you can use a different method for your own project.

Sending a copy

• The simplest way to share is to send your partner a copy of your project folder.
• A zip file packs a whole folder into one compressed file. Windows and macOS both make one from the right-click menu.
• The zip holds every file in the folder. That includes the files you listed in .gitignore, such as API keys and restricted data. Remove them before you send the zip.
• Commit your project before you send it.
• When the changed files come back, copy them in. Read the diff before you commit again.
• Windows: Zip and unzip files →
• macOS: Zip and unzip files and folders →

Shared cloud folders

• If you share a Dropbox, Google Drive, or OneDrive folder with your partner, you both see the same files.
• The service keeps the folder on your computer in sync with a copy online.
• Suppose you and your partner edit the same file at the same time. The service cannot combine the two edits.
  • Dropbox, for example, saves the second version as a separate file, called a “conflicted copy.”
  • Someone then compares the two files by hand.
• Two agents can also overwrite each other’s edits, as Week 3 explained.
• Each service keeps earlier versions of a file for a limited time. On a free Dropbox Basic account the limit is 30 days.
• If your project folder is also a Git repository, your partner’s edits show up in your diff. Read the diff before you commit.
• Sharing a folder: Dropbox · Google Drive · OneDrive
• Earlier versions: Dropbox · Google Drive · OneDrive · Dropbox: What’s a conflicted copy?

Collaboration on GitHub

• GitHub records every change in a commit. You can read each of your partner’s changes before it enters your project.
• First, your partner needs permission to work in your repository.
  • You invite them the same way you invited philohistoria in Week 3.
  • A person you invite is called a collaborator. A collaborator can push to your repository.
• Next, your partner needs your files on their computer. Downloading a copy of a repository, with its full commit history, is called cloning.
• Your partner keeps their edits apart from your version until you have checked them. They work on a separate line of commits in the same repository, called a branch.
  • Every repository starts with one branch, usually called main.
  • Commits on another branch leave main unchanged.
• When the work is done, your partner asks you to add their commits to main. This request is called a pull request.
  • GitHub shows you the diff.
  • You can comment on specific lines, request changes, or approve.
• If you accept the changes, GitHub adds the branch’s commits to main. This is called merging.
• Reading another person’s change before you accept it is called code review.
• Inviting collaborators · Cloning a repository · GitHub flow · About pull requests · Reviewing a pull request

Instructions for a collaborator’s agent

• When your partner opens your project, their agent knows nothing about it.
• The agent reads two files first:
  • the project instructions file, AGENTS.md for Codex or CLAUDE.md for Claude Code,
  • the README.
• If you and your partner use different tools, ask the agent which instructions file it loaded.
• Your global instructions and your memory stay on your computer. Your partner’s agent never sees them.
• Write the decisions your partner needs into those two shared files. Examples:
  • the period the data cover,
  • how each key variable is defined,
  • which files must not change.
• Do not let two agents edit the same file at once. While your partner works in your project, leave the files their task touches alone.
• Codex documentation on AGENTS.md · Claude Code documentation on CLAUDE.md and AGENTS.md

Website and repository

• A reader of your website should find the same policy question, data and figure in your repository.
• Today your partner reads your website and your repository. You read theirs.
• Your website is your GitHub Pages site. It was due before this class as Checkpoint 3 (5%).
• The website presents your project proposal:
  • the policy problem and its audience,
  • the data source, with one figure or table that describes the data,
  • the policy alternatives you will compare,
  • the criteria you will use to judge them.
• Your repository holds the files behind the website:
  • the README,
  • the data,
  • the scripts,
  • the instructions file (AGENTS.md or CLAUDE.md).

Checking the website against the repository

• Check three things:
  • The data source named on the website is recorded in the repository.
  • The figure on the website comes from a script in the repository.
  • The README and the website state the same policy question.
• In this part you only read. You rerun your partner’s code in the next part, Replication.

Feedback on the policy analysis

• The author uses your feedback to revise the project. Write it down.
• Comment on the four parts of the proposal:
  • Problem: is it stated in one sentence, with its audience?
  • Data: does the source fit the question?
  • Alternatives: are there at least two, and could a decision-maker adopt each one?
  • Criteria: can the data show how each alternative does on each criterion?

GitHub issues

• You can post your written feedback as a note on your partner’s repository.
• The note has a title and a description. On GitHub, this kind of note is called an issue.
• Issues are listed in the Issues tab of the repository.
• The owner can reply to an issue and close it once the problem is fixed.
• GitHub documentation on creating an issue →

The purpose of replication

• Another analyst should be able to get your results from your files alone.
• Today your partner tries this with your project. You try it with theirs.
• Rerunning another analyst’s work from their files and checking that you get the same results is called replication.

Reading another person’s code

• Before you run anything, find out what the project is meant to produce.
• Open your partner’s project. Read three things first:
  • the README,
  • the scripts that produce the results,
  • the data documentation.
• Note three things:
  • the policy question,
  • the outputs the project should produce,
  • the commands the README tells you to run.

Summarizing a project with the agent

• You can ask the agent to summarize your partner’s project:

• A summary can name a script or a step that does not exist.
• Check the summary against the files. Open each file it cites.

Rerunning a project

• Next, run the project the way the README describes.
• Follow the README in order.
  • In the terminal, type each command yourself.
  • In the app, ask the agent to run the documented commands and show the output.
• Record three things:
  • what ran,
  • what failed,
  • what information you had to infer.

Diagnosing a failed rerun

• When a command fails, write down the command and its error message.
• Check for these common causes:
  • a file missing from the project,
  • a file path that works only on the owner’s computer,
  • a step the README does not mention,
  • an error in the code.
• Explain the fix needed in the code or in the written instructions.

Checking findings against outputs

• Compare your figures and tables with the findings your partner reports.
• Where a number differs, find the first step where your output and theirs start to differ.

Evidence and policy conclusions

• Identify which findings the evidence supports.
• Identify which claims need further analysis.
• Check how the findings inform each part of the policy analysis:
  • the policy alternatives,
  • the criteria,
  • the recommendation.
• Suggest one useful revision to the analysis or to how it is explained for the intended audience.

Working from written instructions

• Today your partner does one task in your project. You do one task in theirs.
• In each project, the owner is the student whose project it is. The helper is the partner who does the task.
• The helper’s agent knows only what three of the owner’s files say:
  • the instructions file,
  • the README,
  • the task description.
• In Week 5 your partner coded your documents using only your codebook. This task works the same way.
• Each place where the helper gets stuck or has to guess shows a gap in those files.

Task descriptions

• Choose a task your project needs anyway. Examples:
  • a figure,
  • one data-cleaning step,
  • checking a source,
  • a section of your website.
• The owner writes down four things about the task:
  • what to do,
  • which files to use,
  • which files not to touch,
  • what finished looks like.
• This written request is called a task description.
• Save the task description as a file in your project, for example TASK.md.

Carrying out a delegated task

• The helper’s agent works from the owner’s instructions file, README, and task description only.
• The helper writes down every point where they got stuck or had to guess.
• The helper saves questions for the discussion after the work is done.

Reviewing a collaborator’s work

• When the task is done, the two partners go through it together, with the list of guesses.
• The helper returns the work through the sharing method you chose:
  • a copy: send back the changed files,
  • a shared cloud folder: the edits are already there, so tell the owner which files changed,
  • GitHub: push a branch and open a pull request.
• The owner reads the change and decides whether to accept it.
• On GitHub, the owner merges the pull request or closes it.
• To reject a change in your own folder, ask the agent to restore the last committed version of the file.

Revising the instructions file and README

• Each guess the helper made points to a gap in the owner’s files.
• The owner answers each guess in the instructions file or the README.
• Commit and push the revised files.

Replication and collaboration

• Could your partner reproduce your main result from your files alone?
• Which of your policy conclusions did your partner find weakly supported by the evidence?
• What did your partner’s agent guess about your project? What did those guesses show about your instructions file?
• What did the agent help diagnose or repair? What did it miss?
• Several analysts in a government office revise the same analysis. Who should review a change before it enters the official version?

Weekly memo · due Dec 10 before class. Write 1–2 observations from your project or the classroom case: the policy-analysis step you attempted, how AI helped or fell short, and what you would do next. Aim for 150–200 words total. Describe what you actually tried and observed in your own words. Do not use AI to write the memo. Begin in class and submit to Canvas Discussions. See memo grading.

Week 12: Final presentations · Dec 10

In your final presentation, include two things from today:

• what your partner’s replication found,
• what the task changed in your project.