Reviewability

Code, prose, and proof arranged so a reviewer can find the decision and check it.

107 items in this guidance cluster.

Tagged guidance

Code shapeCode-shape guidance covers small source-level moves that reduce live context, improve reader locality, and keep structure changes reviewable. It focuses on local expression shape, cohesion, coupling, reversible structure, and separating behavior from preparation.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.JJ workflowJJ workflow guidance covers source-control inspection, reviewable changes, descriptions, bookmarks, publication, and recovery in jujutsu repositories. It keeps agents and maintainers thinking in jj changes and operations instead of Git-shaped habits.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.

Define good before judgment-heavy workState the quality bar before work where taste, naming, API shape, or review expectations matter. Clear criteria give the agent goalposts before it creates a large speculative diff.Isolate workspaces by taskPut separable or parallel agent work in its own workspace or source-control lane. Isolation keeps diffs, validation, and ownership clear when multiple changes are in flight.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.Preserve intentOptimize for the users underlying objective when literal wording would miss the point. Intent-preserving work keeps changes aligned with the real readability, review, or behavior goal.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.Separate notes from correctionsCapture fast-review notes before fixing them when there are multiple comments or unclear patterns. Separating capture from correction preserves signal and supports coherent follow-up.Spend human attention on ambiguityAsk for human judgment where product behavior, API compatibility, naming, or security posture is still ambiguous. Resolving direction early prevents large speculative diffs.Turn feedback into guidanceConvert repeated review corrections into rules, templates, snippets, or checks. Durable guidance fixes the workflow problem instead of requiring the same steering again.

Avoid speculative public APIAdd public surfaces only when current or accepted callers need them. Waiting for concrete pressure keeps compatibility commitments smaller and easier to validate.Avoid unnecessary dependency churnKeep package, manifest, and lockfile movement out of unrelated work. Separate dependency changes make build, compatibility, and downstream risk reviewable on their own.Isolate controversial changesPut risky or contentious moves in their own review unit when they can stand alone. This lets reviewers approve, reject, or revise the decision without incidental cleanup attached.Minimal but completeKeep the diff as small as the purpose allows while including the evidence that purpose needs. Reviewers should see one coherent unit they can understand, validate, and revert.Prefer small follow-upsMove adjacent cleanup or broader improvements into focused follow-up changes when the current diff can stand alone. This preserves review focus while still capturing useful work.Separate structure from behaviorSplit refactoring or layout changes from behavior changes when the combined diff obscures intent. Separate review units make meaning preservation and new behavior easier to check.Treat and as scope warningUse compound change descriptions as a prompt to inspect whether the work has more than one purpose. The word is not a rule, but it catches scope creep while splitting is still cheap.Use one purpose per changeShape each change around one review question and one reason for existing. Related tests, docs, and generated files can travel with it when they support that same purpose.

Avoid unearned praiseReplace vague ranking words with observable behavior, evidence, or tradeoffs. Use evaluative claims only when the basis is explicit enough for readers to verify.Expose move, risk, and example in patternsGive pattern guidance a recognizable trigger, preferred move, risk, example, and agent instruction. The extra structure makes repeatable advice easier to cite and apply.Group related list itemsCluster long lists under useful names when the relationships matter. Keep short or causal material flat or in prose so structure does not add noise.Keep Markdown lintableUse project Markdown style so formatting stays enforceable and review noise stays low. Treat lint exceptions as intentional local choices, not accumulated drift.Make guidance review state visibleMark guidance maturity so readers know whether a rule is draft, reviewed, or ready for reuse. Visible state prevents tentative advice from becoming an accidental standard.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.Match page shape to reader taskShape pages around the readers task, such as learning, choosing, reference, or review. The right structure lowers scan cost without forcing one page to do every job.Own AI-assisted proseAI-generated or AI-assisted docs are reasonable to share when human curation makes them author-owned. The published artifact should carry checked claims, reader-sized scope, relevant evidence, real tradeoffs, and local voice.Prose for relationships, lists for enumerationUse prose when causality, contrast, or priority matters, and lists when enumerating parallel items. The shape should reveal the relationship instead of hiding it in bullets.Put uncertainty in tracked placesKeep user docs focused on current truth and move unresolved direction to issues, ADRs, or roadmaps. Track speculation where it can be decided instead of implying a promise.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.

Avoid single-run performance conclusionsDo not land performance conclusions from one short benchmark run. Repeat and contextualize timing evidence because warmup, scheduling, cache state, and background load can make a single result non-reproducible.Justify complexity, churn, and dependenciesExplain why a performance win justifies added complexity, churn, unsafe code, caching, or dependencies. Measured speedups still need to pay for the maintenance cost every future reader inherits.Measure goal, change, and comparisonState the performance goal, baseline measurement, implementation change, and comparison result together. Those pieces let reviewers judge whether the patch improved the relevant workload enough to justify its tradeoffs.

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 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 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.Preserve durable answers near sourceTreat 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.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 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 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.Separate discovery, selection, and 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 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 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.

Add benchmarks for performance claimsUse benchmarks when Rust changes rely on speed, allocation, or hot-path claims. The evidence makes performance tradeoffs reviewable instead of relying on intuition.Avoid glob re-exportsRe-export public facade names explicitly instead of using globs. This prevents accidental API expansion and makes exported names visible during review.Consider downstream API impactCheck public API changes against downstream imports, traits, inference, and examples before reshaping them. Additive paths and deprecations often avoid unnecessary breakage.Keep dependency updates intentionalSeparate maintenance-only dependency refreshes from updates that change behavior, features, MSRV, or integration. Reviewable grouping lowers noise without hiding downstream risk.Keep edits scoped to owning conceptChange the module, crate, feature, or facade that owns the behavior being fixed. Scoped edits keep reviews atomic and prevent nearby files from pulling in unrelated concepts.Keep public API shape intentionalMake public visibility, aliases, features, re-exports, bounds, and variants reflect intended commitments. Published surface area becomes something downstream users can depend on.Name auditable intermediatesIntroduce named locals where parsing, validation, rendering, ownership, or side-effect decisions need review. Avoid naming every trivial expression when it would add ceremony without clarifying the boundary.Name tests by behaviorName tests after the behavior, boundary, or regression they protect so failure output is useful before a reader opens the body. Keep names concise and let module context carry repeated setup details.Order code for readingArrange code so central items, callers, or public API appear before supporting helpers when that makes the file readable top to bottom. Prefer the order that reduces reader jumping over mechanical rearrangement.Prefer boring direct codePrefer explicit Rust control flow, types, and error handling over clever framework-shaped indirection. Use macros or abstractions when they remove real repetition or enforce real invariants.Prefer expect for lint suppressionsUse #[expect] for targeted lint suppressions that should disappear when the warning is fixed. Reserve broad allow attributes for deliberate policy choices that are not expected to expire.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.Shape expressions for auditabilityShape complex expressions so ownership, validation, error handling, and side effects can be audited at the point they occur. Break chains or introduce names when density hides a decision readers must verify.Working Rust code not enoughTreat compilation as necessary but insufficient evidence for long-lived Rust code. Review API shape, docs, errors, tests, features, dependencies, and module organization because users and maintainers inherit those choices.

Keep binaries out of source controlStore large or opaque artifacts in systems designed for assets, releases, CI evidence, or external data. Keeping source history textual and reviewable avoids clone cost and painful history rewrites.

Avoid opaque boolean assertionsPrefer comparisons or richer assertions when a predicate hides state needed to diagnose the failure. The first failure should show the useful actual value.Optimize failure outputDesign tests so failures include expected values, actual values, inputs, and contract context where that helps repair. Useful output shortens CI and agent debugging loops.Split unrelated assertionsSplit assertions that diagnose different behaviors when one failure would hide another. Keep checks together only when they express one contract more clearly as a group.

Choose validation by riskMatch the amount and kind of validation to the changed surface and failure cost. Cheap checks come first, but risky or uncertain behavior needs targeted evidence.Keep slow checks out of PR CIKeep long fuzzing, exhaustive matrices, and noisy benchmarks out of required PR CI. Fast gates preserve review flow, while heavier checks belong in release or scheduled validation.Match evidence to surfaceValidate the actual changed surface, such as rendered docs, API behavior, or byte output. The narrowest relevant proof is more persuasive than unrelated broad test success.Run fast format and lint gates earlyRun cheap format and lint gates early in the feedback loop. They remove mechanical failures quickly, but they do not replace validation of risky behavior.

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.Create an operation log point before reshapingCreate a recent jj operation boundary before risky stack reshaping. Recovery is easier when there is a known point before rebases, splits, squashes, or repairs.Duplicate for alternative candidatesUse jj duplicate when two plausible fixes or refactors need independent validation. Separate candidate changes preserve comparison and recovery without mutating the only option.JJ new for review lanesStart unrelated review units with jj new before edits accumulate. Separate changes keep review atomic while leaving later squash or absorb decisions easy.Name exact JJ mutation targetsSpecify revisions, filesets, bookmarks, and destinations for mutating jj commands. Explicit targets make intent reviewable and prevent defaults from acting on surprising state.

Ask what were you trying to achieveRecover the original intent before judging a surprising design. Separating purpose from mechanism makes it easier to preserve useful constraints while replacing stale structure.Cap change radiusBroad diffs increase review cost and make unrelated regressions harder to isolate. Keep the change radius aligned with the requested behavior, using separate chunks for cleanup or adjacent improvements.Characterize then fixBefore fixing incorrect behavior, add a passing test that records the observed result and labels it as known incorrect. Then fix the implementation, update that same expectation to the intended contract, and rewrite the rationale as durable regression context.Choose doc pass depthDocumentation work ranges from quick polish to structural repair, and using the wrong pass depth wastes attention. Match the edit depth to the evidence, risk, and review need before changing the document.Choose doc typeA documentation need can call for a guide, reference, tutorial, decision record, or checklist, and mixing those jobs makes docs harder to use. Pick the type that fits the readers task before deciding structure or tone.Choose good enough toolsTooling choices can become a distraction when the available tool is already adequate for the risk. Prefer the simplest tool that gives trustworthy feedback, upgrading only when accuracy, repeatability, or scale requires it.Chunk statementsDense prose asks readers to hold too many claims at once and hides which idea needs review. Split statements into coherent chunks so each paragraph, bullet, or sentence carries one inspectable purpose.Define good before judgment-heavy workWork that depends on taste or judgment drifts when success is not defined up front. Establish acceptance criteria, examples, and review dimensions before spending effort on subjective iteration.Delete redundant commentsComments that repeat obvious code add reading burden and become stale faster than the behavior they describe. Remove them or replace them with context that explains intent, invariant, risk, or non-obvious tradeoff.Follow local conventionsInconsistent style and structure make each change feel like a new design decision. Start from nearby patterns and only diverge when the local convention cannot support the current need.Keep structure reversibleEarly structure can harden into unnecessary abstraction before the design is proven. Prefer arrangements that are easy to inline, split, merge, or rename until the underlying concept earns permanence.Limit live contextReaders make mistakes when they must keep too many facts active to understand a change. Reduce live context by moving related facts together, naming intermediate concepts, and keeping dependencies local.Make the change easy firstSome changes are risky because the path to make or verify them is unnecessarily hard. First add the smallest harness, boundary, helper, tool, or runbook that makes the real change cheaper to understand and review.Make validation policy explicitValidation rules often differ by workflow even when they touch the same field. Name the policy at the boundary with distinct constructors, modes, policy types, or parsed values once real competing rules exist.Prefer 100-column prose wrapWrap Markdown prose and Markdown-bearing doc comments around 100 columns as a maintainer readability preference. The exact number is subjective, but it balances source reading, monospace density, review diffs, and common screen sizes better than 80 or 120 columns.Reader localityA change can reduce code size while increasing the number of jumps needed to understand one workflow. Keep related concepts near their meaning, extracting only when the new name and location reduce live context.Reconstruct rationale before writingExplanations become plausible stories when writers infer intent from current code and consult history only to fill gaps. Reconstruct the decision from present behavior, introducing and corrective changes, tests, measurements, and discussion before drafting the durable account.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.Separate discovery from editingEditing while still discovering the system can bake early misunderstandings into the diff. Read enough to find the ownership, constraints, and likely change shape before making scoped edits.Separate structure from behaviorDiffs that mix moves, renames, formatting, and behavior make review and rollback harder. Separate behavior-preserving structure from rule changes when each can be checked on its own.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.Smallest trustworthy verificationVerification is weak when it is either skipped or broad without covering the likely failure. Run the cheapest check that could catch the risk introduced by the change, broadening only when shared contracts or user-visible behavior require it.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.Untangle before changingBehavior changes become risky when policy, formatting, validation, persistence, and side effects are braided together. Untangle only enough structure to give the new behavior a clear owner, then keep the behavior change reviewable.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.Mechanize repeated feedbackRepeated corrections should become checks, templates, generators, lints, or reusable guidance when the pattern is stable. Mechanizing the feedback moves human attention back to judgment instead of recall.Reader locality reduces change costCode is cheaper to change when the reader can understand the local decision without distant facts. Keep related state, inputs, side effects, and policy close enough to inspect together.

Guidance content model stewardshipContent-model stewardship keeps guides, rules, patterns, principles, mechanisms, references, snippets, and downstream templates in distinct roles. The mechanism combines mechanical inventory checks with maintainer review queues for overlap, thin guidance, noisy tags, and subjective content-quality decisions.Project operating manualA project operating manual is a repo-owned document that applies broad software guidance to one live codebase. It turns a large catalog of durable rules into an opinionated project-specific doctrine, decision surface, and review contract so maintainers and agents do not have to reconstruct the totality of what matters here from AGENTS.md plus many scattered guides.Source coherence reviewSource-coherence review inventories named declarations separately from behavior, maps both inventories in both directions, and inspects the declaration outline before implementation detail. The pass finds unnamed owners, unjustified abstractions, split facts, misleading modules, and line-count concerns that disappear once docs and tests are distinguished from implementation.

Apply practice guidanceCompact instructions for Codex sessions that need to use the shared practice catalog from another repository. The snippet turns broad standards into a task-local application loop without loading the whole catalog or treating preferences as automatic churn.Full documentation doctrine prompt packLarge single-file prompt pack for long-term documentation maintenance. It combines the repos docs rules with writing, review, anti-drift, and anti-AI-slop lessons drawn from this repo, TidySrc, jk, and Komodo-style documentation cleanup work.Full software doctrine prompt packLarge single-file prompt pack that combines the repos software rules and the reasons behind them into one coherent artifact. This version is tuned for Rust-heavy maintenance and refactoring work, especially when existing code needs to be reshaped toward better locality, coherence, ownership, and documentation.