Agents hand a change back for local review instead of opening the PR - #40
Merged
Conversation
Both files had the agent open the PR and then hand off, which allows a pull request to be opened under the author's name carrying work the author has not read a line of. A PR is a claim that its author stands behind the change, and that claim is false if they have not seen it. Stated as an invariant rather than a procedure, so one rule covers humans and agents: nobody opens a pull request carrying work its author hasn't read. For a human it is nearly free but not empty -- reading your own diff is where debug output, stray files, and data or credentials that were never meant to be committed get caught. For an agent the same rule cannot be satisfied without stopping, because the author is somebody else. Also states that an agent raises open questions with the author rather than in the PR description. A question written into a PR reads as though the author is asking their reviewers: it sponsors a question they never asked and hands the agent's decision to their collaborators. This is the failure that prompted the rule. The pre-merge handoff stays as its own step, since "do not self-merge" is a different handoff from "do not open the PR". The bulk-mechanical-change exception is extended to cover opening as well as merging, on the grounds that twenty PRs needing individual local review is the same friction the exception already exists for. Closes #39 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Updates SwimBlocks contributor/agent workflow guidance to ensure pull requests are only opened after the PR author has personally reviewed the diff, with explicit agent handoff rules that occur before PR creation.
Changes:
- Inserts a new pre-PR step requiring the author to read
git diff main...before opening a PR, and defines the agent consequence (push branch + summarize + wait). - Clarifies that open questions should be raised with the author during handoff rather than placed into the PR description.
- Extends the “large mechanical changes” exception to allow agent-opened PRs (by prior agreement), not just agent-merged PRs.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.
| File | Description |
|---|---|
| CONTRIBUTING.md | Adds a “read before PR” invariant step, reorders handoff steps, and updates the mechanical-change exception wording. |
| AGENTS.md | Replaces “agent opens PR then hands off” with “hand off for local review before PR,” plus guidance on where to raise questions. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #39
What changes
CONTRIBUTING.mdandAGENTS.mdboth had the agent open the PR and then hand off. That allows a pull request to be opened under the author's name carrying work the author has not read a line of.The rule is stated as an invariant rather than a procedure, so it covers humans and agents with one sentence:
For a human it is nearly free but not empty — reading your own diff before opening is where debug output, stray files, and data or credentials that were never meant to be committed get caught. For an agent the same rule cannot be satisfied without stopping, because the author is somebody else, so the handoff falls out as a consequence rather than as a separate regime.
Structure
CONTRIBUTING.md— new step 4 between "Do the work" and "Open a PR". The old step 6 survives as step 7, because do not self-merge is a different handoff from do not open the PR; both are real and they happen at different moments.AGENTS.md§3 — the imperative version, since that file is the distilled summary.Two things worth a look in review
The questions clause. Both files now say an agent raises open questions with the author rather than in the PR description. This is the failure that prompted the issue: an agent's uncertainty written into a PR reads as though the author is asking their reviewers, sponsoring a question they never asked and handing the agent's decision to collaborators.
The exception is extended. The bulk-mechanical-change exception previously covered agent merging; it now covers agent opening too. Reasoning: twenty PRs each needing individual local review is exactly the round-trip friction the exception exists for. Easy to drop if you would rather keep it narrow — this was flagged as an open point on #39.