Guides

Change scope, code shape, Rust API review, documentation, agent work, and jj workflow.

Work areas

Change shape, Rust review, documentation, coding-agent work, and jj workflow each have a guide entry.

Change scope and handoffScope, review shape, validation depth, and handoff.Rust reviewAPI shape, module ownership, docs, tests, dependencies, and release risk.Code shapeLive context, cohesion, and behavior-preserving source moves.DocumentationTask-first, lintable docs that stay close to the behavior they describe.Coding-agent workObjectives, boundaries, context, tools, proof, and reusable feedback loops.JJ workflowReviewable, recoverable local changes aligned with jj source control.

Reader LocalityRefactoringChange 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.Public APIReader LocalityTestingRust MaintainabilityRust maintainability guidance applies the repos software-change preferences to Rust code, APIs, modules, errors, tests, dependencies, documentation, and release risk. It favors Rust that is easy to read locally, hard to misuse, and honest about public behavior.Change ShapeReviewabilityVerificationSoftware 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.

Validation PolicyState TransitionsSide EffectsBoundary CorrectnessBoundary-correctness guidance covers APIs and internal boundaries where uncertain input becomes trusted data, state changes, ambient inputs enter the system, or async work crosses an ownership boundary. It favors visible caller obligations, typed transitions, explicit policy, and provider behavior modeled as it really exists.

Agent WorkflowAgent ContextToolingCoding 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.ReviewabilitySource TruthReview HandoffDocumentation 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.VCS JJChange ShapeReviewabilityJJ 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.RustdocExamplesSource TruthMarkdown And DocumentationMarkdown and documentation guidance covers lintable Markdown, reader paths, page modes, Rustdoc, examples, references, and reusable guidance style. It favors current behavior, task-first user docs, durable source links, and prose that preserves local voice.ErrorsFailure OutputSecurity PrivacyObservability And FailureObservability and failure guidance covers Rust and service boundaries where failures need to be understandable after the fact. It favors structured errors, owned logging boundaries, distinct failure states, safe diagnostics, and enough context for the owner to act.