Documentation Workflow
Documentation-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.
Core Preference
Choose the documentation job before editing. A typo fix, API contract repair, page rewrite, repo map, and PR handoff all have different review costs.
Use Choose Doc Pass Depth when an edit could expand from local correctness into page coherence or documentation architecture. Use Choose Doc Type when the page is mixing task, reference, explanation, or decision-record work.
Source-explanation work is a separate deep pass. Use Run Source Explanation Pass when the goal is to make an undocumented or historically evolved implementation understandable across modules, items, helpers, formulas, and edge paths. Define what a new reader should be able to learn from the checkout, establish the end-to-end system map and domain fundamentals before item detail, and use external references as support rather than required context. Comment count can describe the initial gap, but explanatory coverage and reader comprehension decide completion.
Evidence and Claims
Docs should state current behavior and match their certainty to the evidence. Contracts, tests, measurements, observations, project preferences, and external sources should not sound identical.
Use Label Doc Claims By Evidence when prose uses strong claims, ranking words, or broad guarantees. Use Report Verification Honestly when handoff notes must distinguish run checks, skipped checks, assumptions, and remaining risk.
When code alone does not establish why a choice exists, use Reconstruct Rationale Before Writing. Research from present behavior through introducing and corrective history before drafting. The published explanation should still lead with the current mechanism or tradeoff; history supplies evidence, failed alternatives, and regression warnings rather than the reader's required chronology.
Voice and Shape
Documentation should preserve the useful local voice of a project: its directness, terms, examples, heading density, and level of formality. Generated prose often becomes smooth while losing the project's actual way of explaining tradeoffs.
Structure Pass
Read a draft once for structure, then once for sentence-level tells. The structure pass should cut prose that exists only because the page is explaining itself: teaching-order commentary, page narration, self-justifying text, router prose that an inline link could replace, and repeated helpful framing around the same point.
Claim Strength
Cut recommendation or ranking language when the evidence and tradeoff are not stated. A strong claim should either point to support or be narrowed until it matches what the page can justify.
Local Language
Replace vague abstraction with the concrete host, file, command, resource, type, or behavior. When soft recommendation language hides the real decision, state the tradeoff directly instead of adding another abstract label.
Use Preserve Local Doc Voice when revising existing prose. Use Preserve Intent Over Literalism when a requested rewrite would keep words but lose the decision the original text was carrying. Use Avoid Generated Prose Tells, Use Concrete Details, and Write Technical Prose when revision needs to remove smooth but low-signal prose. Use Own AI-Assisted Prose when docs came from AI generation or AI-assisted exploration and need human curation before they become fair to share.
Review Convergence
Classify review findings as local or systematic. Fix a local error at its source. When one finding reveals a repeated failure in research, coverage, terminology, evidence, safety reasoning, or prose shape, add that failure to the pass checklist and repeat the check across completed scope.
Keep review cycles evidence-producing. Each broad pass should have a named purpose, such as contract correctness, context, rationale depth, path tracing, or generated prose. After a cycle, ask whether the next pass is likely to find a new class of reader error or only alternate wording. Stop when the remaining findings are isolated preferences, repeats of already-fixed patterns, or changes that do not improve a reader's decision enough to justify more churn.
Do not use diminishing returns to excuse an unverified completion claim. Finish declared gates and resolve systematic misses first; use convergence to avoid an endless sequence of undirected review-and-rewrite passes afterward.
Repo Maps and Layers
Repository docs need a small reliable map before they need a large tree. Separate user entry points, maintainer details, reference material, and durable decisions so readers meet depth when they need it.
Use Bootstrap Repo Docs when creating or reorganizing project docs. Use Use AGENTS.md As Map when agent instructions should point to canonical guides instead of becoming a long standalone manual. Use Run Rustdoc Quality Pass when a Rust crate needs README, crate Rustdoc, item Rustdoc, runnable examples, and decision records checked as separate but aligned documentation layers.
Review Narrative
Describing the change is part of the work. PRs, review packets, and jj descriptions should help a reviewer understand purpose, user-facing surface, decisions, validation, deferred work, and the best path through the diff.
Prepare the reviewer before asking for review. A useful review narrative explains the problem, the mental model for reading the diff, where the change diverges from earlier discussion, and which non-goals or deferred work should not become review blockers.
When the implementation changed more than local code, name the decision and its effect. Architecture changes should explain the impact on modules, APIs, boundaries, or flows; observability changes should explain the impact on logs, metrics, traces, diagnostics, or debugging paths; test notes should say what lacks automated coverage and what manual testing covered; documentation notes should say what changed, what stayed accurate, and what still needs a follow-up.
Use inline comments when a decision is best understood next to the relevant code. Use Preserve Durable Answers Near Source when a reviewer question exposes stable knowledge that future readers should not have to rediscover. Remember future readers of reviews: users reading changelogs, contributors tracing motivation, and maintainers root-causing behavior.
Use Write PR Narrative when a change needs a review guide. Use Produce Review Packets when the handoff should bundle summary, proof, artifacts, and known risks. Use Make Review Artifacts Standalone when issues, PRs, commit messages, or agent handoffs need to make sense without private session context.
When a change touches support status, keep docs, examples, tests, fixtures, and user-facing claims aligned. A support matrix or coverage table is only useful when it stays tied to evidence.
Use Keep Drift Claims Aligned when support matrices, fixtures, docs, examples, or public API paths need a shared validation source.
When reviewing docs, lead with correctness, contract ambiguity, risk, drift, and operability. Use severity labels when they help the author separate merge-blocking misunderstandings from polish. Use Review Docs For Correctness And Risk when review feedback needs to separate contract problems from prose polish.
Drift Remediation
Docs drift when behavior changes without nearby explanation changing with it. Treat stale docs as broken contracts: fix them, remove them, or explicitly record the follow-up.
Use Remediate Doc Drift when behavior, examples, command output, public API, or agent instructions no longer match reality. Use Keep Docs Near Their Subject when drift keeps recurring because the doc is too far from the thing it describes.
Agent Snippet
For copyable AGENTS.md guidance, use Markdown And Docs Agent Instructions.
Review Questions
Scope And Evidence
- What documentation job is this change doing?
- Is the pass depth explicit and small enough for the review unit?
- Does the prose state current behavior instead of aspiration?
- Are strong claims backed by contracts, tests, measurements, or sources?
- Was non-obvious rationale reconstructed before drafting rather than inferred and decorated later?
- Does history support the current explanation without forcing readers to reconstruct the present?
Shape And Review
- Does the edit preserve the local voice and density?
- Are user, maintainer, reference, and decision docs in the right layer?
- Does the review narrative explain purpose, surface, validation, and follow-up?
- Did behavior changes update nearby docs, examples, and agent instructions?
- For broad source passes, were small helpers, formulas, producers, return paths, and edge branches audited rather than sampled?
- Did a systematic review miss become a repeated corpus-wide check?
- Did each review pass have a distinct purpose and produce new evidence or a new class of finding?
- Have declared gates and systematic misses been resolved before calling further review diminishing returns?