Reviewability

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

107 items in this guidance cluster.

Tagged guidance

GuideReader LocalityRefactoringChange ShapeCode Shapecode-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.GuideDocumentationSource TruthReview HandoffDocumentation 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.GuideVCS JJChange ShapeToolingJJ Workflowjj-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.GuideChange ShapeVerificationReview HandoffSoftware 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 WorkflowPublic APIDocumentationDefine Good Before Judgment-Heavy WorkAGENT-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.RuleAgent WorkflowVCS JJChange ShapeIsolate Workspaces by TaskAGENT-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.RuleAgent WorkflowReview HandoffChange 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 WorkflowAgent ContextPreserve IntentAGENT-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.RuleAgent WorkflowReader LocalityReview HandoffReview 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.RuleAgent WorkflowAgent ContextChange ShapeSeparate Notes From CorrectionsAGENT-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.RuleAgent WorkflowAgent ContextPublic APISpend Human Attention on AmbiguityAGENT-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.RuleAgent WorkflowDocumentationAutomationTurn Feedback Into GuidanceAGENT-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.

RuleChange ShapePublic APIAvoid Speculative Public APICHANGE-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.RuleChange ShapeDependenciesPublic APIAvoid Unnecessary Dependency ChurnCHANGE-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.RuleChange ShapePublic APIIsolate Controversial ChangesCHANGE-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.RuleChange ShapeVerificationMinimal but CompleteCHANGE-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.RuleChange ShapeDocumentationPrefer Small Follow-UpsCHANGE-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.RuleChange ShapeReader LocalitySeparate Structure From BehaviorCHANGE-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.RuleChange ShapeReader LocalityTreat And as Scope WarningCHANGE-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.RuleChange ShapeVCS JJUse One Purpose per ChangeCHANGE-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.

RuleDocumentationVerificationAvoid Unearned PraiseDOCS-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.RuleDocumentationAgent WorkflowExamplesExpose Move, Risk, and Example in PatternsDOCS-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.RuleDocumentationReader LocalityGroup Related List ItemsDOCS-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.RuleDocumentationToolingLocal ConventionsKeep Markdown LintableDOCS-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.RuleDocumentationSource TruthMake Guidance Review State VisibleDOCS-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.RuleDocumentationReview HandoffMake 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.RuleDocumentationReader LocalityMatch Page Shape to Reader TaskDOCS-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.RuleDocumentationAIReader LocalityOwn AI-Assisted ProseDOCS-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.RuleDocumentationReader LocalityProse for Relationships, Lists for EnumerationDOCS-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.RuleDocumentationSource TruthPut Uncertainty in Tracked PlacesDOCS-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.RuleDocumentationVerificationReview HandoffReview 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.

RulePerformanceVerificationAvoid Single-Run Performance ConclusionsPERF-AVOID-SINGLE-RUN-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.RulePerformanceDependenciesChange ShapeJustify Complexity, Churn, and DependenciesPERF-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.RulePerformanceVerificationMeasure Goal, Change, and ComparisonPERF-MEASURE-GOAL-CHANGE-COMPAREState 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.

RuleReview HandoffAgent 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.RuleChange ShapeVerificationReader LocalityClassify 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.RuleChange ShapeReview HandoffDefine 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.RuleReader LocalityPreserve 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.RuleReview HandoffVerificationDocumentationExplain 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.RuleSource TruthVerificationDocumentationLabel 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.RuleReview HandoffAgent 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.RuleReview HandoffSource 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.RuleChange ShapeAgent WorkflowSeparate 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.RuleSource TruthReview HandoffDocumentationUpdate 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.RuleBoundary CorrectnessOwnershipDocumentationUse 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.

RuleRustPerformanceVerificationAdd Benchmarks for Performance ClaimsRUST-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.RuleRustPublic APIModule LayoutAvoid Glob Re-ExportsRUST-AVOID-GLOB-REEXPORTSRe-export public facade names explicitly instead of using globs. This prevents accidental API expansion and makes exported names visible during review.RuleRustPublic APIChange ShapeConsider Downstream API ImpactRUST-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.RuleRustDependenciesChange ShapeKeep Dependency Updates IntentionalRUST-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.RuleRustChange ShapeOwnershipKeep Edits Scoped to Owning ConceptRUST-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.RuleRustPublic APIChange ShapeKeep Public API Shape IntentionalRUST-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.RuleRustReader LocalityValidation PolicyName Auditable IntermediatesRUST-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.RuleRustTestingFailure OutputName Tests By BehaviorRUST-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.RuleRustReader LocalityOrder Code For ReadingRUST-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.RuleRustReader LocalityPrefer Boring Direct CodeRUST-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.RuleRustToolingAutomationPrefer Expect For Lint SuppressionsRUST-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.RuleRustReader LocalityReview HandoffReview 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.RuleRustReader LocalityValidation PolicyShape Expressions For AuditabilityRUST-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.RuleRustVerificationWorking Rust Code Not EnoughRUST-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.

RuleSource TruthKeep Binaries Out of Source ControlSOURCE-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.

RuleTestingFailure OutputAvoid Opaque Boolean AssertionsTEST-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.RuleTestingFailure OutputErrorsOptimize Failure OutputTEST-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.RuleTestingFailure OutputSplit Unrelated AssertionsTEST-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.

RuleTestingVerificationValidation PolicyChoose Validation by RiskTEST-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.RuleTestingAutomationPerformanceKeep Slow Checks out of PR CITEST-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.RuleTestingVerificationMatch Evidence to SurfaceTEST-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.RuleTestingToolingAutomationRun Fast Format and Lint Gates EarlyTEST-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.

RuleVCS JJVerificationReview HandoffConfirm 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 JJChange ShapeVerificationCreate an Operation Log Point Before ReshapingVCS-CREATE-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.RuleVCS JJChange ShapeDuplicate for Alternative CandidatesVCS-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.RuleVCS JJChange ShapeJJ New for Review LanesVCS-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.RuleVCS JJToolingVerificationName Exact JJ Mutation TargetsVCS-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.

PatternAgent WorkflowAgent ContextDocumentationAsk What Were You Trying To Achieveask-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.PatternChange ShapeReader LocalityCap Change Radiuscap-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.PatternTestingVerificationCharacterize Then Fixcharacterize-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.PatternDocumentationSource TruthChoose Doc Pass Depthchoose-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.PatternDocumentationSource TruthChoose Doc Typechoose-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.PatternToolingLocal ConventionsAgent WorkflowChoose Good Enough Toolschoose-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.PatternReader LocalityChange ShapeChunk Statementschunk-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.PatternAgent WorkflowVerificationDefine Good Before Judgment-Heavy Workdefine-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.PatternDocumentationReader LocalityDelete Redundant Commentsdelete-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.PatternLocal ConventionsChange ShapeFollow Local Conventionsfollow-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.PatternChange ShapeReader LocalityKeep Structure Reversiblekeep-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.PatternReader LocalityAgent ContextLimit Live Contextlimit-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.PatternChange ShapeToolingMake The Change Easy Firstmake-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.PatternValidation PolicyBoundary CorrectnessMake Validation Policy Explicitmake-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.PatternDocumentationLocal ConventionsRustdocPrefer 100-Column Prose Wrapprefer-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.PatternReader LocalityChange ShapeReader Localityreader-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.PatternDocumentationSource TruthAIReconstruct Rationale Before Writingreconstruct-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.PatternVerificationReview HandoffReview 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.PatternAgent WorkflowChange ShapeSeparate Discovery From Editingseparate-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.PatternChange ShapeReader LocalitySeparate Structure From Behaviorseparate-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.PatternChange ShapeReview HandoffSmall 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.PatternVerificationTestingSmallest Trustworthy Verificationsmallest-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.PatternAgent WorkflowReview HandoffSpend 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.PatternChange ShapeReader LocalityUntangle Before Changinguntangle-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.PatternAgent WorkflowReview HandoffUse 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.PatternReview HandoffVerificationWrite 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 ShapeReview HandoffVerificationChange 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.PrincipleAutomationToolingAgent WorkflowMechanize Repeated Feedbackmechanize-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.PrincipleReader LocalityChange ShapeReader Locality Reduces Change Costreader-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.

MechanismDocumentationSource TruthAutomationGuidance Content Model Stewardshipguidance-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.MechanismDocumentationAgent ContextSource TruthProject Operating Manualproject-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.MechanismRustReader LocalityOwnershipSource Coherence Reviewsource-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.

AgentAgent WorkflowAgent ContextSource TruthApply Practice Guidanceagent-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.AgentDocumentationAgent ContextSource TruthFull Documentation Doctrine Prompt Packagent-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.AgentAgent WorkflowAgent ContextSource TruthFull Software Doctrine Prompt Packagent-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.