Source truth

The implementation, primary source, or maintained artifact that settles a disputed claim.

81 items in this guidance cluster.

Tagged guidance

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.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.

Distill from blessed artifactsStudy accepted code, docs, tests, and reviews first. Adapt local convention to this task.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 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 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.

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 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 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 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 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.

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 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 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 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 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 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 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 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 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 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 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.

Record benchmark provenanceRecord the commands, inputs, tool versions, build profile, and runner conditions behind benchmark numbers. Provenance makes future comparisons meaningful and helps separate real changes from environment drift.

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 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 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.

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 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 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 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 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.

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 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 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 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.

Keep drift claims alignedTie support claims, fixtures, examples, docs, and API paths to executable drift checks. Stable claims need evidence, but wording-only changes should not break broad tests.

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 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 truthUse jj for local workflow in repositories with .jj state. This preserves descriptions, stack shape, operation-log recovery, and bookmark semantics.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 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 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 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 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 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 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 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.

Bootstrap 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 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.Code 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 guidanceRepeated steering can expose missing, unclear, unreached, or ignored guidance. Diagnose the failure, fix the current artifact, and repair the instruction or delivery mechanism that should prevent recurrence.Use 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 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.

Docs 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 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.

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.Guidance 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 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.

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.Markdown and docs agent 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 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.