Review Handoff

The context and evidence another person needs to continue or judge the work.

51 items in this guidance cluster.

Tagged guidance

GuideAgent WorkflowAgent ContextToolingCoding Agentscoding-agentsCoding-agent guidance covers task setup, repo-owned context, tools, workspaces, verification, handoff proof, feedback loops, and maintainer review flow. It treats agents as workers in a system whose output should be reviewable, durable, and easy to integrate.GuideDocumentationReviewabilitySource TruthDocumentation Workflowdocumentation-workflowDocumentation-workflow guidance covers deciding what documentation work belongs in a change, how deep the edit should go, and how review-facing prose should carry evidence. It keeps documentation scope explicit so local fixes, page rewrites, repo maps, and review narratives do not collapse into one unreviewable pass.GuideChange ShapeReviewabilityVerificationSoftware Change Preferencessoftware-change-preferencesSoftware-change guidance covers broad preferences for change size, structure, validation, review artifacts, commit history, and handoff. It favors small coherent changes, explicit tradeoffs, and evidence matched to the changed surface.

RuleAgent WorkflowVerificationFeedback LoopsBudget for Feedback LoopsAGENT-BUDGET-FOR-FEEDBACK-LOOPSReserve enough time and tokens for checks, failure inspection, and handoff proof. Planning for the feedback loop keeps validation from being squeezed out after the first edit.RuleAgent WorkflowAgent ContextBoundary CorrectnessGive Objectives With BoundariesAGENT-GIVE-OBJECTIVES-WITH-BOUNDARIESDescribe the outcome, scope, non-goals, forbidden moves, and proof instead of handing over brittle steps. Boundaries preserve intent while leaving room for local implementation choices.RuleAgent WorkflowReviewabilityChange ShapePresent Concrete Next OptionsAGENT-PRESENT-CONCRETE-NEXT-OPTIONSAfter a validated chunk, offer specific follow-up chunks with their tradeoffs. Concrete options let the maintainer steer scope without decoding vague requests to continue.RuleAgent WorkflowVerificationDocumentationProduce Review PacketsAGENT-PRODUCE-REVIEW-PACKETSHand off agent work with purpose, changed files, evidence, skipped checks, risks, and follow-ups. A review packet lets maintainers inspect the output without replaying the session.RuleAgent WorkflowSecurity PrivacyVerificationProve Security ImpactAGENT-PROVE-SECURITY-IMPACTSeparate security hypotheses from proof of reachability, exploitability, assets, and user impact. This keeps prioritization and mitigation tied to demonstrated risk.RuleAgent WorkflowVerificationTestingReport Proof in HandoffsAGENT-REPORT-PROOF-IN-HANDOFFSReplace confidence language with the exact checks, inspection, screenshots, and skipped validation behind a handoff. Proof lets reviewers decide what to trust and what remains risky.RuleAgent WorkflowReviewabilityReader LocalityReview Output as Future MaintainerAGENT-REVIEW-OUTPUT-AS-FUTURE-MAINTAINERReview agent output as someone who will not have the chat transcript. This keeps attention on durable code, docs, tests, validation proof, and residual risk.

RuleDocumentationReviewabilityMake Review Easy to InspectDOCS-MAKE-REVIEW-EASY-TO-INSPECTPackage documentation changes so reviewers can see scope, evidence, and rendered impact quickly. Small inspectable changes reduce hidden drift and style-only review loops.RuleDocumentationReviewabilityVerificationReview Correctness and Risk FirstDOCS-REVIEW-CORRECTNESS-AND-RISK-FIRSTLead documentation review with false contracts, drift, operability, and unsupported claims before style polish. This separates blocking risk from wording cleanup.

RuleReviewabilityAgent ContextAnswer Questions Before CodeREVIEW-ANSWER-QUESTIONS-BEFORE-CODEAnswer reviewer questions before or alongside the code changes that address them. This keeps intent, tradeoffs, and unresolved choices visible instead of burying the reasoning in a new patch.RuleReviewabilityChange ShapeDefine Slices in IssuesREVIEW-DEFINE-SLICES-IN-ISSUESShape issues around review-sized slices with clear outcomes. Coherent slices reduce scope creep and give maintainers or agents a practical unit of work without losing the larger purpose.RuleReviewabilityVerificationDocumentationExplain PR Problem Model and ProofREVIEW-EXPLAIN-PR-PROBLEM-MODEL-AND-PROOFUse PR descriptions to explain the problem, mental model, tradeoffs, validation, and documentation impact. Reviewers can then evaluate the diff against stated intent instead of reverse-engineering it.RuleReviewabilityAgent ContextLet Reviewers Resolve ThreadsREVIEW-LET-REVIEWERS-RESOLVE-THREADSLeave nontrivial review threads for the reviewer to resolve after they confirm the concern was addressed. Authors should only close unambiguous mechanical threads, because resolution carries communication ownership.RuleReviewabilitySource TruthDocumentationMake Review Artifacts StandaloneREVIEW-MAKE-REVIEW-ARTIFACTS-STANDALONEPut the needed problem, decision, context, validation, and risk in the issue, PR, commit, or handoff itself. Standalone artifacts make review and future debugging possible without private session context.RuleReviewabilitySource TruthDocumentationUpdate Source of TruthREVIEW-UPDATE-SOURCE-OF-TRUTHPut durable status changes in the owning issue, PR description, checklist, plan, or handoff instead of posting low-signal comments. Updating the source of truth reduces notification churn and makes the current state discoverable.

RuleRustReviewabilityReader LocalityReview As Future MaintainerRUST-REVIEW-AS-FUTURE-MAINTAINERReview Rust changes for the reader who will debug, extend, or release the code later, not only for immediate correctness. Favor maintainable API shape, docs, tests, and error behavior over changes that merely compile.

RuleSource TruthDocumentationAgent ContextMake Shared Artifacts StandaloneSOURCE-MAKE-SHARED-ARTIFACTS-STANDALONERestate the problem, rationale, evidence, and tradeoffs in shared docs, templates, generated packs, or reusable guidance. Future readers should not need private notes or transcripts to trust the artifact.

RuleVCS JJToolingLocal ConventionsAsk Before Repairing JJ AliasesVCS-ASK-BEFORE-REPAIRING-JJ-ALIASESAsk before changing jj aliases when they disagree with the observed repository topology. Aliases encode workflow policy, so silent repairs can alter future user commands.RuleVCS JJReviewabilityVerificationConfirm Broad JJ OperationsVCS-CONFIRM-BROAD-JJ-OPERATIONSConfirm jj operations that abandon, rebase, squash, split, restore, publish, or go broad. Confirmation protects unrelated work when a command can reshape history or public state.RuleVCS JJReleaseVerificationConfirm GitHub Remote TopologyVCS-CONFIRM-GITHUB-REMOTE-TOPOLOGYInspect origin, upstream, push remote, PR base, and PR head before publication. Fork and owned-repo layouts differ, so defaults can push or target the wrong repository.RuleVCS JJVerificationReleaseDry Run Surprising PublicationVCS-DRY-RUN-SURPRISING-PUBLICATIONUse dry-run for ambiguous or surprising remote publication, not every routine push. Extra verification pays off when remotes, bookmarks, force-like updates, or PR bases are unclear.RuleVCS JJSource TruthMake GitHub Handoff ExplicitVCS-MAKE-GITHUB-HANDOFF-EXPLICITName bookmark, remote, base, head, and repo when handing coherent jj state to GitHub. Explicit publication avoids host-tool inference mistakes in forks, stacks, and multi-remote repos.RuleVCS JJSource TruthToolingMatch JJ Topology to Repo RoleVCS-MATCH-JJ-TOPOLOGY-TO-REPO-ROLEAlign fetch remotes, push remotes, tracked bookmarks, aliases, and PR bases to repo role. Owned, maintainer, and fork-only workflows need different topology assumptions.RuleVCS JJSource TruthToolingRepair Remote Topology CoherentlyVCS-REPAIR-REMOTE-TOPOLOGY-COHERENTLYRepair fetch, push, tracking, trunk alias, PR base, and PR head assumptions together. Remote topology is coupled, so partial fixes can leave publication commands half-correct.RuleVCS JJSource TruthTrack Remotes ExplicitlyVCS-TRACK-REMOTES-EXPLICITLYSet explicit remote tracking when the same bookmark name exists on multiple remotes. This prevents fetch, rebase, and publication ambiguity in fork and upstream workflows.RuleVCS JJAgent WorkflowToolingUse Git-Formatted Diffs for AgentsVCS-USE-GIT-FORMATTED-DIFFS-FOR-AGENTSPrefer jj diff --git when agents or patch-oriented tools need diff text. Git patch format preserves hunks and paths in a shape those consumers can parse reliably.

PatternAgent WorkflowVerificationFeedback LoopsClose The Agent Loopclose-the-agent-loopAgent work is incomplete when it stops at edits without checking the result or explaining residual risk. Finish the loop by validating, reporting evidence, and making the next human decision clear.PatternVCS JJSource TruthCommit Messages For Historycommit-messages-for-historyCommit messages become future debugging and review aids, not just publication labels. Write them to explain the reason and effect of the change, with enough context to survive outside the original conversation.PatternDocumentationSource TruthDocument Intentional Non Goalsdocument-intentional-non-goalsReaders may treat missing behavior as oversight when the absence was a deliberate scope choice. Record important non-goals where they prevent repeated debate or misuse without turning the document into a defensive catalog.PatternAgent WorkflowSource TruthMake Plans Versioned Artifactsmake-plans-versioned-artifactsChat-only plans are difficult to review, resume, cite, or keep current once work spans sessions. Put substantial plans in the repository with goals, constraints, progress, decisions, and open questions, while keeping obvious one-step edits lightweight.PatternAgent ContextAgent WorkflowPreserve Agent Context Coherencepreserve-agent-context-coherenceMixing unrelated work pollutes the sessions attention, working-copy state, and handoff narrative. Keep each session and jj change focused on one purpose, splitting work when ownership, validation, or review decisions diverge.PatternAgent WorkflowAgent ContextPreserve Intent Over Literalismpreserve-intent-over-literalismLiteral compliance can violate the users actual goal when a request touches risky, privileged, or externally visible actions. Infer the safe operating intent and stop when policy, review expectations, or irreversible consequences conflict with the words alone.PatternVerificationAgent WorkflowProduce Review Packetsproduce-review-packetsReviewers lose time when a handoff contains only a diff and no acceptance evidence. Package the goal, validation, risks, and proof artifact in proportion to the review burden.PatternSecurity PrivacyVerificationProve Security Impactprove-security-impactSecurity reports create noise when they imply exploitability without showing reachability or consequence. Prove the attacker path and impact, or clearly label the finding as an unproven hypothesis.PatternVerificationReport Verification Honestlyreport-verification-honestlyHandoffs become risky when verification is overstated, omitted, or blurred with assumptions. Report exactly what ran, what passed or failed, what was not checked, and what risk remains.PatternReviewabilityVerificationReview Proof Not Just Codereview-proof-not-just-codeCode review is weaker when it inspects the diff without checking whether the claimed behavior was proven. Ask for the smallest trustworthy evidence that the change works and that the likely failure mode was covered.PatternChange ShapeReviewabilitySmall Reviewable Chunkssmall-reviewable-chunksLarge mixed changes blur structure, wording, behavior, and workflow decisions until review becomes slow or shallow. Choose one coherent purpose per chunk, validate it, and ask for direction before expanding into preference-sensitive follow-up work.PatternAgent WorkflowReviewabilitySpend Human Attention On Ambiguityspend-human-attention-on-ambiguityAgent throughput can exceed the maintainers ability to review and steer. Delegate execution and inspection, but reserve human attention for ambiguous goals, taste, architecture, risk, and the systems that make future delegation safer.PatternAgent WorkflowReviewabilityUse Narrow Agent Reviewersuse-narrow-agent-reviewersBroad review prompts often miss specific risks or return vague feedback. Add focused agent reviewers for important, repeatable concerns when narrow context will produce more useful findings than another general pass.PatternReviewabilityVerificationWrite PR Narrativewrite-pr-narrativeA correct diff can still waste reviewer attention when it lacks purpose, risk, review order, and verification. Write the PR narrative as a guide to the decision the reviewer needs to make, scaled to the burden of the change.

PrincipleChange ShapeReviewabilityVerificationChange Shape Controls Review Costchange-shape-controls-review-costChange boundaries determine how much intent, risk, validation, and revert cost a reviewer must reconstruct. Use the smallest coherent unit that preserves trust without splitting one decision into noise.PrincipleVCS JJToolingJJ Topology Is Repo Role Dependentjj-topology-is-repo-role-dependentJJ publication behavior depends on whether the checkout is owned, maintained, or fork-based. Align remotes, bookmarks, trunk, and GitHub handoff with that role before mutating public state.PrincipleAgent ContextDocumentationSource TruthPrivate Context Is Not Shared Contextprivate-context-is-not-shared-contextShared artifacts must carry the reasoning that downstream readers did not see in the private session. Issues, PRs, commits, guides, and review packets should restate the decision context that matters.

MechanismVCS JJAgent WorkflowToolingJJ Agent Workflowjj-agent-workflowNoninteractive jj defaults, topology checks, and local override conventions make agent source-control work safer. The mechanism keeps local workflow state explicit without leaking private checkout assumptions into shared artifacts.

AgentAgent WorkflowAgent ContextToolingCoding Agent Workflow Instructionsagent-coding-workflow-instructionsCompact workflow instructions for repositories that delegate implementation or review work to coding agents. The snippet emphasizes objectives, boundaries, durable handoff, repo-owned context, and feedback that becomes reusable guidance.AgentAgent WorkflowAgent ContextVerificationCore Agent Instructionsagent-core-instructionsBroad baseline instructions for coding agents working in repositories that adopt these development preferences. The snippet keeps AGENTS.md short while routing agents to canonical guides, principles, mechanisms, and the reviewed rule pack.AgentVCS JJAgent WorkflowToolingJujutsu Agent Instructionsagent-jj-instructionsCompact source-control instructions for coding agents working in repositories that use jujutsu. The snippet covers fresh changes, descriptions, non-interactive commands, recovery, remote handoff, and publication approval.AgentDocumentationRustdocSource TruthMarkdown And Docs Agent Instructionsagent-markdown-docs-instructionsCompact documentation instructions for agents editing Markdown, Rustdoc, READMEs, review notes, or adjacent narrative. The snippet focuses on current behavior, local voice, page purpose, drift repair, and markdownlint-compatible formatting.