Diátaxis-shaped documentation skeleton.
After installing user-guide-diataxis, your repo has a `guides/` directory shaped to the Diátaxis framework — separate directories for tutorials, how-to guides, reference, and explanation. The `new-guide` skill scaffolds each new document in the correct category, preventing the most common documentation failure: mixing instruction and reference in the same document.
new-guide2 gatesScaffolds a new guide document in the correct Diátaxis category — tutorial, how-to, reference, or explanation — with the right structure and tone for that category.
You identify a gap in the project’s documentation — something users need to know that isn’t written down, or is written in the wrong form. The agent activates new-guide, asks what the guide needs to cover, and helps classify it into the correct Diátaxis category.
You: Make the classification decision at the G-classify gate. This is the most consequential decision in the documentation session — the wrong category means the wrong structure, the wrong voice, and the wrong reader. If you’re unsure between how-to and tutorial, ask: is this reader learning, or is this reader doing? Learning → tutorial. Doing → how-to.
With the category confirmed, the agent scaffolds the guide in the correct guides/ subdirectory and drafts the content — entry conditions, steps or information organized by category structure, and exit conditions.
You: Watch the draft take shape. For how-tos: check that every step is an action, not a paragraph of explanation. Explanation belongs in a linked explanation document. For tutorials: confirm the reader can follow the steps sequentially and arrive at a working outcome, not just a theoretical understanding.
After the draft completes, you review at the G-review gate for structure consistency and category fidelity, then the agent opens a PR.
You: Read the guide as a first-time reader — not as the author who knows what it means. If you have to re-read a sentence twice to understand what action it’s asking for, it needs rewriting. If a paragraph of background explanation appears in the middle of a how-to, flag it for extraction into a linked explanation document. Merge after the review gate passes.
For each gate, everything you need to make a confident decision.
A clear category choice that you could explain in one sentence: 'This is a how-to because the reader already knows what they want to do and just needs the steps.'
An 'explanation' that includes step-by-step instructions, or a 'how-to' that spends the first half explaining why the tool exists. These are the two most common Diátaxis violations — each mixes a different reader need into the same document.
A document in the wrong Diátaxis category doesn't fail loudly — it just fails its readers silently. Tutorials that are secretly how-tos frustrate experienced readers. Explanations that embed instructions confuse newcomers who needed a tutorial. The classification gate catches this before the first paragraph is written.
A document that a reader could pick up cold, complete, and close — knowing exactly what they learned or accomplished. The entry and exit states are explicit.
A document that assumes the reader knows something that wasn't stated in the entry conditions. Or a how-to that ends with 'now you know how X works' — which is the exit state of an explanation, not a how-to.
A badly structured guide ships quietly and gets read by users who then file support requests or give up. Catching structure problems at the review gate is the cheapest point in the lifecycle — after a document is live, it accumulates readers who expect stability.
agentbundle install --pack user-guide-diataxis