Pull requests as pedagogy: teaching the four moves your engineering team has been making all along

## 1. The PR is not a Git feature. It is a teaching move. If you walk a new contributor through their first pull request, you will notice something strange. The Git mechanics — `git checkout -b`, push, open a PR — take maybe ten minutes to demonstrate. The *judgment* underneath takes a career to develop: which change to bundle, what to write in the description, who to ask for review, when to merge, what to leave for the next PR. Most "what is a pull request" tutorials cover the first ten minutes and leave the career. I want to invert that. The mechanics are easy to look up. What is hard, and worth teaching deliberately, is the underlying instrument. A pull request is a self-contained pedagogical exchange. It packages a piece of work, a thesis statement about that work, and an invitation to be corrected. That triplet — work, claim, invitation — is the same shape as a writing assignment, a math proof, a science fair project, or a classroom presentation. We are not training students to use Git when we teach them to make PRs. We are training them to make small, defensible, auditable claims about reality. Git is just where this particular exchange happens to live. This matters now in a way it did not five years ago. The contributors opening pull requests on a modern team are no longer all human. On the sof.ai repo at https://github.com/DearMrFree/sof-ai-repo, more than half of the merged pull requests were opened by an autonomous agent (Devin) and reviewed by both humans and other agents (Claude, Gemini). If we want to teach this practice well — to humans and to the agents we trust to ship — we have to teach the underlying moves, not just the keyboard shortcuts. In the rest of this paper I will name those moves and show each one in a real merged PR. ## 2. The four moves Reframe the PR as four pedagogical moves stacked on top of each other: 1. **Delegation** — choosing what *not* to do in this PR. The diff is the physical evidence of a delegation choice. 2. **Description** — explaining the diff in language that lets a stranger know whether to trust it. The title and body are the artifacts. 3. **Discernment** — judging whether the diff and its description match reality. The review thread is where this happens. 4. **Diligence** — proving the change is safe to merge with mechanical evidence: tests, lint, type checks, CI. Each move corresponds to a teaching skill that long predates software. Delegation is the choice of what to put on the syllabus and what to leave for next semester. Description is the abstract on a thesis paper. Discernment is what a peer reviewer does to a manuscript. Diligence is what a lab partner does when they re-run your experiment to see if your graphs hold up. Engineering culture absorbed all four from research and education and bound them into a single artifact called the pull request. The artifact is the curriculum. Let us look at each move. ### 2.1 Delegation: the diff A pull request that touches twenty files in unrelated subsystems is not a "big PR." It is *several* PRs that have been illegally stapled together. This is the most common failure mode for new contributors, and it is a delegation failure: they did not decide what to leave out. Take [PR #38 in the sof.ai repo](https://github.com/DearMrFree/sof-ai-repo/pull/38), which adds the `/welcome` six-question onboarding wizard, an `user_type` enum, a searchable directory at `/u`, and audience-specific deep links from the landing page. Each of those is a separate concern — onboarding, taxonomy, directory, marketing — but they ship together because *that* is the delegation: the smallest coherent unit that delivers user-visible onboarding. Splitting it further would have left half-built screens in production. Bundling it more would have hidden a real change inside an unrelated refactor. The diff is where you teach taste. New contributors should be asked, on every PR: *what did you choose not to include here, and why?* That question makes them practice delegation as a deliberate act, not a side-effect of running out of time. ### 2.2 Description: the title and body A pull request that says only "fix bug" is not lazy — it is *unteachable*. There is no claim in it for anyone to interrogate. The reviewer cannot say "you said this would fix X, but I think it only fixes Y." The CI output cannot be compared against a stated intent. The future engineer trying to understand why a line of code exists has nothing to read. Look at [PR #41](https://github.com/DearMrFree/sof-ai-repo/pull/41) on sof.ai. Its title is "admin: PR #40 follow-up — fix SSE data-loss when heartbeat + queue fire together." Its body explains the exact race condition: when `asyncio.wait` returns multiple ready tasks in the same round, the heartbeat branch was running first and the queued event was being silently dropped. Pre-fix, no visible failure: the dashboard would just miss new signups about once every fifteen seconds of activity. Post-fix, a regression test pins the behavior. That description does the same work as a research paper's abstract: it states the problem, the mechanism, the fix, and the evidence. It also does something an abstract cannot — it lets *future* readers, including agents grepping for prior art, find this fix when they encounter the same race elsewhere. This is why "fix bug" titles are not just unhelpful; they degrade the team's collective memory. When I teach this move I ask new contributors to write the title before they write the code. If you cannot say in twelve words what you are about to do, you have not yet decided what to do. The title is a commitment device. ### 2.3 Discernment: the review The review is where the PR stops being a piece of work and becomes a piece of teaching. Without a review, a PR is just a pile of code that nobody read. With a review, the same pile becomes a conversation about whether the world the diff describes matches the world we want to live in. A good review is not a list of style nits. It is the reviewer thinking out loud: "I see what this change is doing — does it interact correctly with the thing I added last month? Is this the lowest-friction way to express it? Is the regression risk worth the feature value?" Those are discernment questions. Style nits are diligence (covered below); they belong in lint configs, not in a senior engineer's review time. On sof.ai we let three reviewers — Devin, Claude, and Gemini — each read every pull request automatically. Each one writes a structured review: an approve/reject verdict, a one-sentence summary, and a few paragraphs of reasoning. [PR #42](https://github.com/DearMrFree/sof-ai-repo/pull/42), which shipped the digital twin model, was approved by all three and merged. [The retract endpoint inside it](https://github.com/DearMrFree/sof-ai-repo/pull/42/files) was flagged by Devin's review specifically — the schema reused `ProposeSkillIn`, which enforces `proposed_text: min_length=1`, so every retract from the browser was returning HTTP 422 before the handler even ran. That review caught a shipped-but-broken feature that no human reviewer noticed in the same fifteen minutes. The fix landed in [PR #43](https://github.com/DearMrFree/sof-ai-repo/pull/43), with a regression test that exercises the actual browser body shape so the schemas can never be re-coupled silently. This is the pedagogy: a reviewer is a co-thinker who has the right and the duty to say "I don't think this is true yet." That is also a reviewer's job in a writing workshop, in a grant committee, in a PhD defence. The PR is the same exercise in a different costume. ### 2.4 Diligence: CI Diligence is the move humans want to skip and shouldn't. It is the mechanical, unglamorous re-running of every test, type check, lint, and build, on every commit, on every PR, before merge. It exists because software has a property writing does not: it can break in ways that are trivial to detect mechanically and devastating if missed. CI is where that detection lives. The teaching move here is *separating discernment from diligence*. A human reviewer reading a 600-line diff and trying to mentally run every test is doing both moves at once and doing both badly. That is why modern PRs gate on green CI before a human even reviews. By the time the reviewer is looking, the test suite, the lint, and the type checker have already done what they can do. The reviewer is freed to focus on what only a human (or a well-instructed agent) can do: judgment. When CI fails, the teaching opportunity is not "fix the red square." It is "tell me what failed, in your own words, before you start fixing it." That sentence forces the contributor to actually read the failure output, which is the only way to develop the skill of reading failure output. Every shortcut here — re-running CI without reading it, silencing a flake without diagnosing it — is a missed lesson. ## 3. Teaching the moves to humans If you are an educator approaching pull requests for the first time as a classroom artifact, here is the smallest practice that produces the biggest gains. Have students open three pull requests of increasing size against a real, deployed project (not a toy). Specifically: - **PR 1: a typo fix or one-line README change.** The point is to rehearse the *ritual* without any code judgment in the way. Branch, diff, push, open, merge. Twenty minutes. Mechanics only. - **PR 2: a single-feature change with a written description.** Now they are practising delegation (what's in, what's out) and description (the body). Ask them to write the title before they touch code. - **PR 3: a change that requires reading someone else's code first.** Now discernment enters: they must form a mental model of code they did not write before changing it. Their PR description must explain what they discovered, not just what they changed. After each PR, do not ask "did it work?" Ask the four questions: 1. What did you delegate away? *(diff)* 2. What did you claim, in twelve words? *(title)* 3. What did the reviewer want you to think about more carefully? *(review)* 4. What did the test suite catch that you didn't see? *(CI)* These four questions, asked across thirty pull requests, do more for an engineer's judgment than any course on Git mechanics. ## 4. Teaching the moves to agents The agents currently shipping production code — Devin, Claude Code, the agentic features inside Cursor and Copilot Workspace — are graded on the same four moves, just with different failure signatures. A diff-bound agent that bundles unrelated changes fails the delegation move; you correct it by tightening the scope of the task you ask it to take. An agent that opens a PR titled "implement feature" fails the description move; you correct it by requiring the title and body to be written before the diff is presented for approval. An agent whose review of another agent's PR consists of "looks good" is failing discernment; you correct it by giving it review rubrics with specific things to check (security, schema regression, backward compat, observability). An agent that ships without running the existing test suite fails diligence; you correct it by withholding merge until CI goes green. This is, structurally, the same correction loop you run with a human junior engineer. The difference is throughput. A human gets maybe ten PRs of corrective feedback before the lesson sticks. An agent can take two hundred PRs of feedback in a week, because the loop is automated and the agent does not get tired. That throughput is why "agentic teaching" is an active discipline now and not just a thought experiment. On sof.ai we treat each merged PR as a teaching artifact for the *next* PR. Every reviewer's reasoning is stored, classified, and folded back into the system prompt of the agent that wrote it. The next time that agent makes the same delegation mistake, an earlier instance of itself will already have flagged it in the prompt. That is teaching, applied to a worker that does not forget. ## 5. The four moves are the curriculum If I had to compress this paper into a single recommendation for educators, it would be: the next time you assign your students a software project, do not assign the project. Assign three pull requests against the project. Grade the pull requests on delegation, description, discernment, diligence — in that order — not on whether the code "works." Code that works without those four moves is brittle, unteachable, and unsafe to give an agent that is going to extend it next week. Code that has been through the four moves can be passed forward — to the next student, the next agent, the next decade — and remain legible. That is the difference between writing software and *teaching software*. The pull request is how the second one happens at scale.