esond/docs

Router for documentation work under the Diátaxis methodology. Use whenever the user wants to write, add to, expand, reorganize, or audit documentation — "write docs for X", "document this feature", "add a page about", "improve our README", "does this doc work", "audit our docs", "--audit" — or mentions Diátaxis, the compass, or a documentation type when no single type skill is the obvious match. Applies the compass (action or cognition? acquisition or application?) to classify the reader's need, then hands off to diataxis-tutorial, diataxis-how-to, diataxis-reference, or diataxis-explanation. When the user points at existing docs or supplies paths, assume the work is adding to or expanding those articles. With --audit, runs an improvement pass instead: classify each unit, run the matching type's drift checklist, and propose relocations and splits that fit the docs to the model without rewriting their substance. Prefer this router over a type skill whenever the type isn't already certain.

Write, expand, or audit explanation — understanding-oriented documentation in the Diátaxis sense: discursive discussion that deepens the reader's grasp of a topic, read away from the work itself. Use whenever the user wants an architecture overview, design-rationale or "why did we build it this way" doc, concept guide, background or theory piece, ADR-style context, a "philosophy of X" or "about X" article, or asks to capture the reasoning behind a decision — even if they never say "explanation". Also loaded by the diataxis router when the compass points to cognition + acquisition: the reader wants to *understand*, as *study*. If the content is facts to consult mid-work, that's diataxis-reference; if it directs a task, that's diataxis-how-to. When the type is in doubt or mixed, consult the diataxis skill first.

Write, expand, or audit a how-to guide — goal-oriented documentation in the Diátaxis sense: directions that help an already-competent reader accomplish a specific real-world task. Use whenever the user wants a "how to X" doc, a runbook, playbook, recipe, troubleshooting guide, setup/configuration/ migration/deployment/integration instructions, or step-by-step directions for practitioners — even if they never say "how-to guide". Also loaded by the diataxis router when the compass points to action + application: the reader will *do* something to *get work done*. If the reader is a beginner who needs to learn by doing in a safe setting, that's diataxis-tutorial instead; if the content mostly enumerates options and facts, that's diataxis-reference. When the type is in doubt or mixed, consult the diataxis skill first.

Write, expand, or audit reference documentation — information-oriented technical description in the Diátaxis sense: austere, accurate, consistent facts about the machinery, consulted while working. Use whenever the user wants API docs, a configuration or parameter listing, CLI or command documentation, an options table, schema or data-model docs, error-code catalogs, environment-variable docs, or any "document what X is / what settings exist" request — even if they never say "reference". Also loaded by the diataxis router when the compass points to cognition + application: the reader needs *facts to consult* while *getting work done*. If the content is mostly why-and-context discussion, that's diataxis-explanation; if it directs the reader's actions step by step, that's diataxis-how-to. When the type is in doubt or mixed, consult the diataxis skill first.

Write, expand, or audit a tutorial — learning-oriented documentation in the Diátaxis sense: a lesson that takes a beginner through a guided, hands-on experience to build skill and confidence, where the artifact produced along the way is not the point. Use whenever the user wants a "getting started" guide, onboarding walkthrough, "first steps with X", intro lesson, learning exercise, workshop material, or asks to "teach someone" a tool, API, or codebase by doing — even if they never say "tutorial". Also loaded by the diataxis router when the compass points to action + acquisition: the reader will *do* something in order to *learn*. If the reader is an already-competent practitioner trying to get a real job done, that's diataxis-how-to instead; when the type is in doubt or mixed, consult the diataxis skill first.