---
name: tend-docs
description: Write or update a technical documentation page in the chalk voice, structured around Diataxis. Use when the user says "tend the docs", "update the docs", "write a docs page", "document this feature", "add a how-to for X", "/chalk:tend-docs", or references adding/editing an end-user-facing docs page in a technical project.
version: 0.1.0
user-invocable: true
disable-model-invocation: false
---

# Tend — Technical Documentation

Interpret MUST, MUST NOT, SHOULD, SHOULD NOT, MAY, etc. per RFC 2119.

Write or update a docs page for a **technical audience** — developers, operators, integrators.
This skill is not for marketing copy, end-user help aimed at non-technical readers, or general-audience prose.
If the user asks for those, decline politely and suggest a different approach.

## Your Responsibilities

1. **Name the audience.**

   Before writing, know who you're writing for.
   Technical is not specific enough — pick one:

   - **Newcomer** — has never used this product.
     Needs just enough context to evaluate or get started.
     Will re-read.
   - **Returning power-user** — has used it before, coming back for a specific detail.
     Skims, looks up, leaves.
     Values terseness.
   - **Operator mid-task** — is running this thing in production and needs to make it do a thing now.
     Values step-order and concrete identifiers.
   - **Developer integrating** — is wiring this into their own code.
     Values signatures, examples, failure modes.

   Different audiences change everything — pacing, depth, what's assumed, what's spelled out.
   If you can't tell from the page's location and surrounding pages, **ask**.

2. **Identify the Diataxis quadrant(s).**

   Diataxis names four quadrants: **tutorial**, **how-to**, **reference**, **explanation** (see the `chalk:voice` skill).
   Each page leans toward one at the top level; each sub-section within it may hit a different quadrant.

   The test isn't "where does this page live?" — it's "what is *this paragraph/section* for?".

   Before writing, decide:
   - What quadrant is this page as a whole?
   - What quadrant is each section?

   Don't blur them.
   A how-to section that drifts into explanation loses the reader mid-task; an explanation section that drifts into reference buries the mental model.

3. **Discover project conventions.**

   Conventions differ between projects and this skill does not prescribe them.
   Read the repo before writing.

   In order of priority:
   - A docs README (e.g. `docs/README.md`) — if present, it's the authoritative style guide.
     Follow it even where it disagrees with your defaults.
   - A `CLAUDE.md` at the repo root or in the docs directory.
   - Existing sibling pages — match their shape (frontmatter, heading depth, changelog format, version-marker style, callout syntax, cross-link style).
   - Recent commits and PRs touching docs — they show what's been landing.

   Project-specific conventions you're looking for:
   - **Frontmatter** shape (title, description, sidebar fields, etc.).
   - **Version markers** — is there an inline marker convention like `(v2.1+)`?
     Does it go on headings, in code comments, both?
   - **Changelog blocks** — does each page carry a `<details>` changelog?
     What's the format?
     What counts as a transition vs. an additive feature?
   - **Callout style** — Starlight `:::note` / `:::caution`, MDX admonitions, plain blockquotes?
   - **Cross-link style** — site-relative paths?
     Anchors?
     What's the house convention?
   - **Diagrams** — inline D2, Mermaid, PNG assets?

   Where the project has a convention, match it.
   Where it doesn't, make a call and be consistent within the page.

4. **Pull the "why" from the issue-graph neighbourhood.**

   Like `chalk:commit`, this skill draws *motivation* from upstream context.
   Cast the net at least one hop beyond the immediately-tracked issue — a single issue rarely carries all the reasoning that ends up mattering on a docs page.

   Read:

   - The **tracked chalk issue** and its comments — the primary source.
   - **Related issues** — parent, sub-issues, blocked-by, blocks.
     See the "Issue Relationships" section of the main chalk skill; the one-hop graph surfaces operational context, rejected alternatives, and why-now that don't fit in any single issue.
     The github agent's neighbourhood query is the cheapest way to pull this.
   - The **landing PR(s)** — description *and* review discussion.
     Review discussion in particular catches edge cases and invariants that only got clarified during review.
   - The **landing commit body(ies)** — multi-commit PRs often have per-commit rationales the PR description glosses over.

   For a feature that's touched multiple issues and PRs, read across them — contradictions between old and new thinking usually mark where the docs need the clearest framing.

   These carry the *why* that isn't visible in the code — root causes, operational guarantees, invariants, rejected alternatives, real-world failure modes.
   They noticeably improve the resulting docs.

   Distil, don't copy.
   A chalk comment is author-to-maintainer; a docs page is author-to-user.
   The audience is different; the phrasing has to be too.

5. **Apply the chalk voice.**

   **Load the `chalk:voice` skill** (via the Skill tool) for the Diataxis framing and universal principles, then apply the quadrant-specific voice to each section.
   Don't restate those rules inline — they live in `chalk:voice`.

   **Line format: sentence-per-line.**
   A docs page is checked into the repo and reviewed as a `git diff`, so put each sentence on its own line — it keeps diffs minimal (a one-sentence edit touches one line) and the structure scannable in source.

6. **Ask clarifying questions** — don't invent.

   The main chalk skill's "Understanding Why" rule applies here: if the *why* isn't obvious from the issue graph, the PR, or the conversation, ask.
   A one-sentence answer from the user beats a fabricated rationale every time, and fabricated rationales in docs are particularly corrosive — they look authoritative and they rot silently.

   Ask when:

   - The **audience** isn't clear from the page context.
   - The **quadrant** isn't clear from the request ("document X" is ambiguous — tutorial, how-to, reference, or explainer?).
   - The **why** isn't clear from the issue graph / PR / commits, and the section needs one.
     Don't make it up.
   - A **project convention** is missing and the call has material effect on the output (e.g. no changelog-format precedent and the change is a transition worth recording).

## Constraints

- The audience MUST be named (to the user or in a code comment on the draft) before the page is written.
- Each section MUST commit to one Diataxis quadrant.
  Sections MUST NOT blur quadrants.
- The page MUST follow the `chalk:voice` skill — universal principles plus the quadrant-specific voice — and be written sentence-per-line (a docs page is reviewed as a diff).
- Project-specific conventions (version markers, changelog shape, frontmatter fields, callout style) MUST be discovered from the repo, not invented.
- The skill MUST decline (politely) if asked to write for a non-technical audience — that's not what this skill is for.
- If chalk is active, the skill SHOULD read the tracked issue, its one-hop issue-graph neighbourhood, and the landing PR(s) before writing a non-trivial section — the *why* lives across them, not in any single artefact.
- The skill MUST NOT fabricate a rationale for a section when the issue graph / PR / commits don't carry one.
  Ask the user instead (see the main chalk skill's "Understanding Why" section).

## Workflow

1. Parse the user's directive (update page X, write a page about Y, add a section to Z).
2. Locate the docs tree.
   Read the docs README if present; otherwise scan sibling pages for conventions.
3. Name the audience.
   If ambiguous, ask.
4. Identify the quadrant of the page (and each section).
5. Pull the *why* from chalk context — tracked issue, one-hop neighbourhood (parent/sub/blocked-by), landing PR(s) including review discussion, and landing commit body(ies).
6. Draft.
   Apply the `chalk:voice` skill — universal principles plus per-quadrant voice; write sentence-per-line.
7. Match discovered project conventions (frontmatter, version markers, changelog, callouts, cross-links).
8. Ask clarifying questions if the audience, quadrant, or a material project convention is unclear.

## Chalk Integration

When chalk is active (tracking a GitHub issue):

- **Read the issue and its comments** before writing a non-trivial section — the chalk comments are the richest source of reasoning.
- **After updating the page**, update the chalk comment directly — don't ask first.
  Chalk updates are part of the work, same as with `chalk:commit`.
- A docs change is often a natural checklist item on the chalk progress section ("document X behaviour"). Check it off when the page lands.

## What this skill is not

- Not a marketing-copy writer.
- Not a spec for non-technical end-user help.
- Not an opinion on how *any specific project* should organise its docs — conventions come from the repo.
- Not a drift-detector — for "which pages does this diff affect?", use `chalk:weed-docs`.