---
name: write-tutorial
description: Use when the user says "write a how-to for {feature}" / "tutorial for {integration}" / "walk a user through {flow}" — produces a Diátaxis-aligned tutorial (learning-oriented, concrete end-to-end flow the reader can run) with overview, prerequisites, numbered steps with working code blocks, troubleshooting, next steps. Draft only; never publishes to a docs site.
---

# Write Tutorial

## When to use

- User: "write a how-to for {feature}" / "tutorial for {integration}" /
  "walk a user through {flow}" / "draft a learn-by-doing doc for {X}".
- Diátaxis framing: this is **tutorial mode** — learning-oriented,
  concrete, complete end-to-end. Not how-to-mode (problem-oriented)
  or reference-mode (information-oriented) or explanation-mode
  (understanding-oriented).

## Steps

1. **Read engineering context.** Open
   `../head-of-engineering/engineering-context.md`. If missing or
   empty, stop and tell the user:
   > "I need the engineering context doc before I can write a
   > tutorial that fits your product. Run the Head of Engineering's
   > `define-engineering-context` first."

2. **Read config.** `config/docs-home.json` (where the tutorial will
   live shapes metadata / cross-links) and `config/doc-audience.md`.

3. **Resolve inputs.** Two required:
   - **Feature name** (e.g. "Send webhooks", "Connect Stripe",
     "Deploy to Fly").
   - **Target user persona** (e.g. "backend developer integrating
     our API", "solo founder setting up billing").
   If persona is missing, ask ONE question:
   > "Who's the reader — a developer integrating our API, a new
   > operator doing setup, an end user? One line is fine. I'll save
   > it to `config/persona.md` so I don't ask again."
   Save `config/persona.md` (markdown, one paragraph).

4. **Gather grounding material.** Only use what's verifiable:
   - The feature's code path (via `composio search code-hosting`
     if a repo is connected + the feature name points to a module,
     route, or component).
   - The OpenAPI spec entry if the feature is an API endpoint.
   - Any existing docs in the repo under `/docs` or similar.
   - **Optional:** `composio search web-search` for canonical
     examples of similar tutorials to model structure on (e.g. "how
     Stripe teaches webhook setup"). Never copy specific code or
     claims from search results — only structure.
   If a code path is referenced but not accessible, mark UNKNOWN and
   ask.

5. **Draft the tutorial.** Diátaxis tutorial-mode shape — the reader
   must be able to follow along and end up with a working thing.

   ```markdown
   # {Tutorial title — verb + outcome, e.g. "Send your first webhook"}

   **Audience:** {persona}
   **Time:** {estimated minutes}
   **Outcome:** By the end you'll have {concrete result — "a webhook
   firing to your test endpoint every time a widget is created"}.

   ---

   ## Overview

   {2-3 sentences on what you'll build and why — what problem it
   solves for the reader. Keep it tight; don't oversell.}

   ## Prerequisites

   - {Account / tool 1 — e.g. "An account on example.com"}
   - {Installed tool + version — e.g. "Node.js 20+"}
   - {API key / credential — where to get it, one sentence}
   - {Working knowledge assumption — one line}

   ## Step 1 — {verb + outcome}

   {One-line context of why this step.}

   ```bash
   {copy-pasteable command}
   ```

   Expected output:
   ```
   {what the reader will see}
   ```

   If you see something different, see Troubleshooting below.

   ## Step 2 — {verb + outcome}

   ...

   ## Step 3 — {verb + outcome}

   ...

   (3-7 numbered steps, each with: context sentence, command or code
   block, expected output, "if you see X instead, go to
   troubleshooting".)

   ## Verify it works

   ```bash
   {end-to-end check command}
   ```

   You should see {concrete evidence the tutorial worked}.

   ## Troubleshooting

   ### `{error message verbatim}`
   {Cause + fix, 1-3 lines.}

   ### {Another common failure mode}
   {Cause + fix.}

   (2-4 entries; cover the top ways this fails in practice. If
   unknown, write "If you hit something else, file an issue at
   {repo URL}".)

   ## Next steps

   - {Adjacent tutorial the reader might want next.}
   - {The reference doc for the feature.}
   - {One advanced angle — e.g. "handle retries", "sign requests".}

   ---

   **Source code cited:** {file paths / commits / spec entries — so a
   future maintainer can audit the tutorial against the real code.}
   ```

6. **Grounding rules — strict.**
   - Every command and code block is runnable or marked `# pseudocode`.
   - Every claim about the feature cites the code or spec. If the
     feature does X, cite the file/function that implements X.
   - If you had to invent a plausible example (e.g. example domain,
     fake API key), mark it clearly with `$REPLACE_ME` or
     `your-domain.com`.
   - If a step depends on an external service changing (e.g. a
     dashboard UI), note "as of {date}" and flag that it may drift.

7. **Write** to `tutorials/{slug}.md` atomically (`*.tmp` → rename).
   Slug is kebab of the tutorial title (e.g. `send-your-first-webhook.md`,
   `connect-stripe-billing.md`).

8. **Append to `outputs.json`** (`type: "tutorial"`,
   `title: "Tutorial — {title}"`, `summary: "{persona} tutorial:
   {N} steps, estimated {M} min. Covers: {1-line what}"`,
   `path: "tutorials/{slug}.md"`, `status: "draft"`, timestamps).
   Read-merge-write atomically.

9. **Summarize to user** — one paragraph: what the tutorial teaches,
   who it's for, the runtime estimate, any UNKNOWN flags, and the
   path. End with: "Paste into your docs site or commit under `/docs`.
   I never publish."

## Hard nos

- **Never invent the product's behavior.** Every code block and
  claim cites a real file or spec entry. Unknowns get UNKNOWN +
  TODO notes.
- Never publish to a connected docs tool directly — draft only.
- Never write without reading `engineering-context.md` first.

## Outputs

- `tutorials/{slug}.md`
- Appends to `outputs.json` with `{ id, type: "tutorial", title,
  summary, path, status: "draft", createdAt, updatedAt }`.