Review handoff

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

51 items in this guidance cluster.

Tagged guidance

Coding 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.Documentation 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.Software 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.

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.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.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.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.Prove security impactSeparate security hypotheses from proof of reachability, exploitability, assets, and user impact. This keeps prioritization and mitigation tied to demonstrated risk.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.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.

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.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.

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.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.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.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.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.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.

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.

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.

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.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.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.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.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.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.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.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.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.

Close 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.Commit 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.Document 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.Make 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.Preserve 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.Preserve 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.Produce 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.Prove 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.Report 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.Review 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.Small 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.Spend 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.Use 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.Write 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.

Change 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.JJ 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.Private 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.

JJ 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.

Coding agent 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.Core agent 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.Jujutsu agent 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.Markdown and docs agent 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.