Source Truth
The implementation, primary source, or maintained artifact that settles a disputed claim.
81 items in this guidance cluster.
Tagged guidance
Guide items
Documentation 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.Markdown And Documentationmarkdown-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.
Agent Workflow rules
Distill From Blessed ArtifactsAGENT-DISTILL-FROM-BLESSED-ARTIFACTSStudy accepted code, docs, tests, and reviews first. Adapt local convention to this task.Keep Durable Context on DiskAGENT-KEEP-DURABLE-CONTEXT-ON-DISKStore project facts, accepted decisions, and long-lived operating notes in files instead of relying on chat context. Durable context makes future sessions and reviews resumable.Suggest Local Override FilesAGENT-SUGGEST-LOCAL-OVERRIDE-FILESPut checkout-only facts in ignored override files instead of shared guidance. Local overrides keep machine-specific steering useful without leaking it to every contributor.Use AGENTS.md as MapAGENT-USE-AGENTS-MD-AS-MAPKeep AGENTS.md compact by using it to route agents to deeper guides and mechanisms. Treating it as a map preserves startup context without losing durable project guidance.
Boundary rules
Ground Integrations In Primary SourcesBOUNDARY-GROUND-INTEGRATIONS-IN-PRIMARY-SOURCESBase adapter behavior on provider docs, specs, or captured API responses before encoding local assumptions. When primary sources are incomplete, label observations and inferences so guesses do not become fake guarantees.Keep One Authoritative Owner Per FactBOUNDARY-KEEP-ONE-AUTHORITATIVE-OWNER-PER-FACTGive each state fact one definite authority and derive other views from it where practical. Cached, persisted, or adapter-specific projections may duplicate a fact only when their source and invalidation or reconciliation contract are explicit.Model Real Upstream SurfaceBOUNDARY-MODEL-REAL-UPSTREAM-SURFACEShape local integration APIs around the providers actual records, pages, permissions, rate limits, and consistency behavior. Wrappers may simplify common paths, but they should not promise capabilities the upstream cannot provide.Parse Uncertainty At EdgeBOUNDARY-PARSE-UNCERTAINTY-AT-EDGEParse and validate raw strings, JSON, CLI args, provider responses, and user input at the boundary before passing values inward. Core logic receives typed invariants, while domain-specific checks that require later context remain explicit policy decisions.Track Dynamic Registration ProvenanceBOUNDARY-TRACK-DYNAMIC-REGISTRATION-PROVENANCEStore stable source names, versions, paths, owners, or generated identifiers for extension, guest, generated-code, and config registrations. Provenance makes conflicts and failures diagnosable while avoiding sensitive source details.
Documentation rules
Align README and Crate RustdocDOCS-ALIGN-README-AND-CRATE-RUSTDOCKeep README and crate-level Rustdoc consistent where users learn setup and supported behavior. Let the pages serve different tasks, but prevent conflicting contracts.Choose Document TypeDOCS-CHOOSE-DOCUMENT-TYPEPick the dominant document mode before editing so the page serves one reader task well. Link out to secondary modes instead of blending tutorial, reference, decisions, and changelog.Compare Libraries AccuratelyDOCS-COMPARE-LIBRARIES-ACCURATELYCheck current upstream behavior before comparing nearby libraries or crates. Charitable, source-backed comparisons preserve trust while still helping users choose.Make 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.One Dominant Mode per PageDOCS-ONE-DOMINANT-MODE-PER-PAGELet each page have one primary mode and move competing material behind links. This keeps readers from paying for tutorial, reference, explanation, and policy at once.Put 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.README as Entry PointDOCS-README-AS-ENTRY-POINTUse README files to orient readers to purpose, setup, first useful use, and deeper docs. Split out manual-level detail when it hides the starting path.Separate Technique From Example PolicyDOCS-SEPARATE-TECHNIQUE-FROM-EXAMPLE-POLICYTraining examples should distinguish the library or framework technique being taught from application-specific policy. Explain the policys rationale, tradeoffs, and meaningful edge cases, then tell readers what to reuse and what to reconsider.State Current Behavior, Not AspirationDOCS-STATE-CURRENT-BEHAVIOR-NOT-ASPIRATIONDescribe what the system does now and label limitations or future plans separately. Otherwise roadmap language becomes a false contract for readers and agents.Treat Docs as ContractsDOCS-TREAT-DOCS-AS-CONTRACTSTreat supported behavior, commands, errors, and examples in docs as promises readers may rely on. Separate normative claims from background, examples, and future plans.Use Source Links as SupportDOCS-USE-SOURCE-LINKS-AS-SUPPORTUse references to verify, frame, or contrast local guidance instead of supplying the wording. This keeps the repo voice original while still making claims checkable.
Performance rules
Review rules
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.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.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.
Rust rules
Align Release Support ClaimsRUST-ALIGN-RELEASE-SUPPORT-CLAIMSKeep crate metadata, docs, changelogs, and support statements saying the same thing. The alignment helps downstream users know which compatibility contract to trust.Compare Crates by Fit and TradeoffRUST-COMPARE-CRATES-BY-FIT-AND-TRADEOFFCompare adjacent crates by intended fit, scope, and constraints instead of broad superiority claims. This helps users choose without turning docs into brittle marketing.Document Current Implemented BehaviorRUST-DOCUMENT-CURRENT-IMPLEMENTED-BEHAVIORDocument what the crate does today instead of presenting future plans as available contract. Clear tense and labels prevent callers from relying on unimplemented behavior.Keep Markdown Outside Rustdoc PurposefulRUST-KEEP-MARKDOWN-OUTSIDE-RUSTDOC-PURPOSEFULUse standalone Markdown for architecture, workflow, release, or operational guidance that would make API docs noisy. Choosing the right surface keeps contracts and long-form context current.Keep Rustdoc and README Examples AlignedRUST-KEEP-RUSTDOC-AND-README-EXAMPLES-ALIGNEDKeep README, Rustdoc, generated docs, and example directories teaching the same current usage contract. Aligned examples prevent users from guessing which import path or lifecycle is correct.
Source rules
Generalize Project-Specific RulesSOURCE-GENERALIZE-PROJECT-SPECIFIC-RULESExtract the portable failure mode before promoting local lessons into shared guidance. Provider, repo, or tool details should stay local unless they clarify the durable rule.Keep 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.Make Shared Artifacts StandaloneSOURCE-MAKE-SHARED-ARTIFACTS-STANDALONERestate the problem, rationale, evidence, and tradeoffs in shared docs, templates, generated packs, or reusable guidance. Future readers should not need private notes or transcripts to trust the artifact.Prefer Primary Stable SourcesSOURCE-PREFER-PRIMARY-STABLE-SOURCESAnchor durable guidance in sources readers can inspect, compare, and challenge. Use links to clarify judgment, not to decorate rules or depend on private memory.
Testing rules
VCS rules
Do Not Fall Back to Git for JJ IssuesVCS-DO-NOT-FALL-BACK-TO-GIT-FOR-JJ-ISSUESDiagnose jj locks, pager issues, and state problems through jj before switching tools. Git bypasses jj change-graph semantics, so use it only for transport after jj state is coherent.Inspect Sparse StateVCS-INSPECT-SPARSE-STATECheck sparse checkout state before treating a missing path as absent from history. Sparse patterns can hide files, so inspection prevents recreating or editing the wrong path.JJ as Source of TruthVCS-JJ-AS-SOURCE-OF-TRUTHUse jj for local workflow in repositories with .jj state. This preserves descriptions, stack shape, operation-log recovery, and bookmark semantics.Make GitHub Handoff ExplicitVCS-MAKE-GITHUB-HANDOFF-EXPLICITName bookmark, remote, base, head, and repo when handing coherent jj state to GitHub. Explicit publication avoids host-tool inference mistakes in forks, stacks, and multi-remote repos.Match JJ Topology to Repo RoleVCS-MATCH-JJ-TOPOLOGY-TO-REPO-ROLEAlign fetch remotes, push remotes, tracked bookmarks, aliases, and PR bases to repo role. Owned, maintainer, and fork-only workflows need different topology assumptions.Recover with Operation LogVCS-RECOVER-WITH-OPERATION-LOGUse jj operation-log recovery before destructive cleanup habits. The operation log preserves recoverable graph states, but inspect the target before restoring.Repair Remote Topology CoherentlyVCS-REPAIR-REMOTE-TOPOLOGY-COHERENTLYRepair fetch, push, tracking, trunk alias, PR base, and PR head assumptions together. Remote topology is coupled, so partial fixes can leave publication commands half-correct.Scope JJ File TrackingVCS-SCOPE-JJ-FILE-TRACKINGPass intended paths to jj file track and jj file untrack. Scoped tracking keeps local-only, generated, or unrelated files out of publication state.Track Remotes ExplicitlyVCS-TRACK-REMOTES-EXPLICITLYSet explicit remote tracking when the same bookmark name exists on multiple remotes. This prevents fetch, rebase, and publication ambiguity in fork and upstream workflows.Treat Bookmark Remote Syntax as Version SensitiveVCS-TREAT-BOOKMARK-REMOTE-SYNTAX-AS-VERSION-SENSITIVEVerify bookmark@remote and remote-bookmark syntax against the installed jj version. Durable guidance should avoid assuming one spelling works across commands and releases.Use Evolog and Operation LogVCS-USE-EVOLOG-AND-OPERATION-LOGUse jj evolog for a changes evolution and jj op log for repository operations. Picking the right log distinguishes rewrite history from workspace, bookmark, and import events.
Pattern items
Bootstrap Repo Docsbootstrap-repo-docsRepositories without a documentation map make newcomers infer structure from scattered files and conventions. Add the smallest durable entry points that explain purpose, layout, commands, and where deeper guidance belongs.Choose 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.Choose 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.Code Is Memory Of Processcode-is-memory-of-processCode accumulates the history of decisions, shortcuts, and workflows that produced it. When changing it, preserve useful operational memory while removing obsolete process scars that no longer serve readers.Commit Messages For Historycommit-messages-for-historyCommit messages become future debugging and review aids, not just publication labels. Write them to explain the reason and effect of the change, with enough context to survive outside the original conversation.Distill From Blessed Artifactsdistill-from-blessed-artifactsDurable guidance should come from accepted examples, reviewed decisions, and working artifacts rather than transient preferences. Distill stable lessons from blessed sources and keep uncertain ideas marked as draft.Document Intentional Non Goalsdocument-intentional-non-goalsReaders may treat missing behavior as oversight when the absence was a deliberate scope choice. Record important non-goals where they prevent repeated debate or misuse without turning the document into a defensive catalog.Document System Mental Modelsdocument-system-mental-modelsSystems with implicit concepts force readers to reconstruct how parts fit together from scattered implementation details. Document the mental model that explains ownership, flow, boundaries, and vocabulary before listing procedures.Garbage Collect Agent Driftgarbage-collect-agent-driftAgent-generated notes, plans, and assumptions can outlive their usefulness and mislead later work. Periodically remove, update, or promote them so durable guidance stays current and temporary scaffolding does not become false context.Keep Docs Near Their Subjectkeep-docs-near-their-subjectDocumentation drifts when it is far from the code, policy, or workflow it explains. Let shared rationale rise to the nearest stable owner while item docs retain their local contracts, differences, edge cases, and side effects.Keep Name Currentkeep-name-currentNames that preserve old intent make readers distrust the code or documentation around them. Rename when the concept changes enough that the old name now teaches the wrong model.Label Doc Claims By Evidencelabel-doc-claims-by-evidenceDocumentation loses trust when speculation, observed behavior, policy, and verified facts look the same. Label claims by their evidence level so readers know what can be relied on and what still needs confirmation.Make Plans Versioned Artifactsmake-plans-versioned-artifactsChat-only plans are difficult to review, resume, cite, or keep current once work spans sessions. Put substantial plans in the repository with goals, constraints, progress, decisions, and open questions, while keeping obvious one-step edits lightweight.Manage Agent Work Not Sessionsmanage-agent-work-not-sessionsInteractive sessions do not scale when the maintainer must remember every thread, terminal, and handoff. Represent agent work as durable tasks with states, owners, validation, and review criteria so humans spend attention on priorities and judgment.Optimize For Long Term Coherenceoptimize-for-long-term-coherenceAgent-produced work can satisfy a prompt while weakening the systems future concepts, names, boundaries, and tests. Choose the smallest change that preserves long-term direction without using coherence as an excuse for speculative architecture.Prefer Durable Summariesprefer-durable-summariesImportant context is costly when every reader must rediscover it from implementation details, but exhaustive narration becomes stale. Capture stable invariants, rationale, boundaries, or side effects in short summaries that survive nearby changes.Preserve Local Doc Voicepreserve-local-doc-voiceDocumentation edits can become bland or mismatched even when they are grammatically correct. Patch only what needs changing while keeping local terms, structure, density, and tone unless the existing voice blocks clarity or accessibility.Reconstruct 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.Record Agent Operating Lessonsrecord-agent-operating-lessonsAgent work produces useful operational knowledge that is easy to lose after the task succeeds or fails. Record reusable lessons in the right durable place so future runs inherit the improved workflow instead of rediscovering it.Remediate Doc Driftremediate-doc-driftDocumentation drift misleads readers when behavior, workflow, or project shape has moved on. Fix the source of truth and nearby references together, choosing whether the code or the doc represents the intended contract.Run Source Explanation Passrun-source-explanation-passTurn a source tree into a self-contained reading environment by recovering its mental models, fundamentals, decisions, constraints, and edge cases. Establish the system map before item detail, audit every relevant helper and path, and measure success through reader comprehension rather than comment count.Turn Feedback Into Guidanceturn-feedback-into-guidanceRepeated steering signals that a preference is missing from durable repo guidance or tooling. Fix the current artifact and encode the reusable lesson at the right level when the feedback applies beyond one line.Use Disk As Context Sinkuse-disk-as-context-sinkLarge pasted context is difficult to search, diff, summarize, and revisit. Put bulky or reusable context on disk so agents can pull the relevant slice while the thread stays focused on decisions and handoff.Write Docs As Contractswrite-docs-as-contractsBehavior and obligations become surprising when they are only discoverable by reading implementation details. Treat docs as part of the change surface, updating contracts and rationale alongside the code they describe.
Principle items
Docs Are Contractsdocs-are-contractsDocumentation near code is part of the supported behavior surface. Keep prose, examples, and implementation aligned so humans and agents can rely on the same contract.Private Context Is Not Shared Contextprivate-context-is-not-shared-contextShared artifacts must carry the reasoning that downstream readers did not see in the private session. Issues, PRs, commits, guides, and review packets should restate the decision context that matters.
Mechanism items
Guidance 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.Guidance Generation And Auditguidance-generation-and-auditGenerators and audits keep rule indexes, compressed agent snippets, downstream templates, and Markdown synchronized. The checks catch recurring drift so review attention stays on judgment instead of mechanical bookkeeping.Project 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.
Agent items
Apply 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.Full 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.Full 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.Markdown And Docs Agent Instructionsagent-markdown-docs-instructionsCompact documentation instructions for agents editing Markdown, Rustdoc, READMEs, review notes, or adjacent narrative. The snippet focuses on current behavior, local voice, page purpose, drift repair, and markdownlint-compatible formatting.Reviewed Rule Agent Packagent-reviewed-rule-packGenerated compact execution surface for every reviewed rule. The pack gives agents stable rule IDs and instructions while leaving rationale, examples, and deeper context in the canonical rule files.