Guides
Change scope, code shape, Rust API review, documentation, agent work, and jj workflow.
Broad decisions that span rules, patterns, principles, and mechanisms.
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.
Available guides
Documentation, agents, and source control
Documentation, agent handoff, jj workflow, and review-facing context.
Boundary 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.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.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.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.Markdown 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.Observability 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.Rust 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.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.