Private Context and Review Artifacts
Review artifact rules cover issue slices, PR narratives, ADRs, speculation labels, thread ownership, and artifacts that stand alone without private session context.
Issues, PR narratives, ADRs, review packets, and shared context.
11 rules
Answer 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.Classify Prototype ReuseREVIEW-CLASSIFY-PROTOTYPE-REUSEClassify whether a rebuild is reusing behavior, evidence, replaceable internal shape, or load-bearing boundaries. That separation helps preserve proven compatibility while discarding prototype scaffolding.Define 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.Explain 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.Label Speculation as Inferred or UnknownREVIEW-LABEL-SPECULATION-AS-INFERRED-OR-UNKNOWNMark review claims as observed, inferred, assumed, or unknown when the evidence level matters. Clear labels keep guesses from hardening into false project knowledge.Let 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.Make 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.Preserve Durable Answers Near SourceREVIEW-EXPLAIN-CONTROVERSIAL-CHOICES-INLINETreat capable reviewer questions about non-obvious code as documentation signals. Preserve the durable answer at the closest appropriate source boundary so future readers do not have to rediscover it.Separate Discovery, Selection, and ImplementationREVIEW-SEPARATE-DISCOVERY-SELECTION-IMPLEMENTATIONSplit problem discovery, solution selection, and implementation review when they require different decisions. This keeps design debate out of patch correctness review once scope or direction is still unsettled.Update 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.Use ADRs for Boundaries and OwnershipREVIEW-USE-ADRS-FOR-BOUNDARIES-AND-OWNERSHIPRecord durable ownership, API, storage, topology, runtime, or service-boundary decisions in ADRs. A decision record gives later contributors a stable tradeoff to affirm, revise, or replace.