Playbook step template

When to use

• Shelf: build/playbooks/.../NN-step.mdx with stepNumber in frontmatter
• kind: playbook step (also usable for procedural SOPs/runbooks that walk a sequence)
• Diátaxis mode: how-to (action) within a tutorial journey
• Readers served: beginners (TL;DR + note callout); agents (# Expected: + checklists as blockers); perfectionists (explicit verify items)

Part of the Playbook set (3 of 3): overview · phase hub · step.

Full rules: Writing style → Playbook step pages.

Design rationale

• Goal-first TL;DR — how-to docs must state outcome before steps so readers can bail early if wrong doc (Diátaxis how-to guides).
• Checklist as gate — unchecked boxes are blockers for agents and ADHD closure for humans (checklist manifesto — cognitive aid).
• Verb-first ### sub-steps — procedural docs scan by action, not noun labels (Google style — procedures).
• # Expected: after commands — separates command from observable success; agents need machine-checkable signals (technical writing — show results).
• :::next not bare links — consistent exit ramp for sequential tutorials (Starlight structural callouts).
• Actor legend once per playbook — repeating 🤖/👤 on every step adds clutter (writing-style reader profiles).

Copy-paste skeleton

---
title: "N · Step title"
description: One sentence — what this step does and what done looks like.
sidebar:
  label: "N · Step title"
  order: N
phase: "N"
stepNumber: N
estTime: ~30 min
status: current
tags: [playbook, topic]
---

## TL;DR

{Goal first — the outcome this step achieves. Then who it's for and what done looks like. Plain language, no undefined jargon.}

:::note[For beginners and agents]
Read the **TL;DR** first, follow the numbered steps in order, then check **every** box in the checklist before advancing. Agents: treat unchecked items as blockers — log command output as evidence (`# Expected:` in code blocks).
:::

*Actor legend — 🤖 Agent · 👤 User · 🔀 mix — appears **once** in the playbook overview, not on every step. Steps are agent-doable by default; only 👤/🔀 steps carry a `:::note[Who does this]` callout.*

## Background

{Optional — plain prose: context, scope, or prerequisites. **Not** a callout under this heading. Delete this whole section when the step needs no setup; the spine is then just TL;DR → Steps.}

## Steps

### 1. Set up the first thing

One or two sentences: what this step does and why. *(🤖 agent-doable → no "Who does this" callout.)*

\`\`\`bash
command --flag   # Expected: success message or exit 0
\`\`\`

- Expected: `<what you should see>` — exit 0, a "ready" line, or a new file/row.

### 2. Add your license key

One or two sentences: what this step does and why.

:::note[Who does this]
👤 **User** — paste it in the vendor dashboard (browser). *(🔀 use **User + Agent** for a mix.)*
:::

…

## Checklist

Do not mark this step done until **every** box below is checked.

- [ ] First outcome verified (how you know it's done)
- [ ] Second outcome verified
- [ ] No secrets committed; `.env` still gitignored (if applicable)

:::next[Next step]
[Next step title](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/01-ai-system/03-project-constitution/)
:::

Anti-patterns

• Do not ship a :::summary[TL;DR] callout — use the ## TL;DR heading.
• Do not use ## Completion checklist — it’s ## Checklist.
• Do not use bare ## Gate sections or ✅ prose gates — use - [ ] items.
• Do not end with a trailing Next: line without :::next.

Worked example

• Machine setup
• System docs examples

Sources

• Diátaxis — How-to guides — goal-oriented procedural docs within larger journeys.
• Google developer documentation style guide — Procedures — verb-first steps and expected outcomes.
• The Checklist Manifesto (Atul Gawande) — verification lists as cognitive and safety aids.
• Diátaxis — Tutorials — step pages as actions inside tutorial playbooks.
• Writing style → Playbook step pages