Revision is substantial modification of proposed software changes after review identifies concerns about implementation, scope, or correctness. Repeated revision can leave a pull request cycling through review, updates, and further requests. section 8.6
Treat revision as a collaboration problem, not merely an author problem. Unclear design, ambiguous acceptance criteria, unfamiliar coding standards, or misunderstood comments can all create avoidable rework. section 8.6 section 8.5
When substantial revision is needed:
- Summarize the concerns in the pull request and state that a direct conversation will follow. section 8.5
- Discuss the changes synchronously, clarify the reviewer’s reasoning, listen to the author, and confirm shared understanding. section 8.5
- Define design decisions and acceptance criteria before implementation, and use review milestones when coaching teammates who need more guidance. section 8.6
When revisions still miss the comments
A reviewer sees that updated changes do not address earlier comments. Rather than extending asynchronous back-and-forth, they document a clarification conversation, contact the author directly, explain the remaining issues, and continue until both are confident they agree. section 8.5
