Playbook Part template

When to use

• Shelf: build/playbooks/.../<NN-phase>/<NN-part>.mdx with partNumber in frontmatter (stepNumber is a legacy alias only).
• kind: playbook Part — the .mdx document-level unit inside a Phase.
• Diátaxis mode: tutorial/how-to chunk inside a larger Phase.
• Readers served: humans who need one focused chunk of work; agents that execute every Step, expected result, and checklist box before advancing.

Part of the Playbook set (4 page levels): overview · phase hub · Part · single Step.

Full rules: Writing style → Playbook Parts.

Design rationale

• Part names the missing level — a Phase spans multiple .mdx documents, and each document often contains several ## Steps; calling that document a Step creates an execution collision.
• Goal-first TL;DR — action docs state outcome before the procedure so readers and agents know what “done” means before touching the repo (Diátaxis how-to guides).
• Checklist as gate — unchecked boxes are blockers for agents and closure aids for humans (The Checklist Manifesto).
• Verb-first Step headings — Steps scan by action, not noun labels (Google style — procedures).
• # Expected: after commands — observable success is part of the procedure, not a nice-to-have (Google style — code samples).
• Agent autonomy stays full-coverage — Part prompts execute every Step/sub-step/checklist item unless the user explicitly asks for a limited mode.

Vocabulary

Level	Canonical name	Definition	Rendering
Playbook	Playbook	The whole outcome journey	Folder / collection
Phase	Phase	Major stage with a Gate	Phase-hub index.mdx
Part	Part	Chunk of a Phase grouping several Steps	One .mdx document
Step	Step	Numbered action inside a Part	## Steps item / ### N. heading
sub-step	sub-step	Verb-first nested action inside a Step	Nested list or lower detail

Copy-paste skeleton

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

## TL;DR

{Goal first — the outcome this Part 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 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 Part. Steps are agent-doable by default; only 👤/🔀 Steps carry a `:::note[Who does this]` callout. Authentication, account creation, and password/secret entry are always 👤; the agent resumes after the session or non-secret state exists.*

## Background

{Optional — plain prose: context, scope, or prerequisites. Delete this whole section when the Part needs no setup.}

## 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 Part 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 Part]
[Next Part title](/tech-stack/laravel/codecanyon/build/playbooks/setup-new/01-ai-system/03-project-constitution/)
:::

Anti-patterns

• Do not call this a Step when it contains multiple Steps; the document-level unit is a Part.
• Do not use stepNumber for new Part documents; it remains only for legacy compatibility.
• 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 title or describe the Part with source-only task IDs or old phase labels; map them to the current playbook.
• Do not make a routine tracker or project-state update a user question.
• Do not leave a required branch as prose like “if needed” without a test command, expected result, and on-fail path.

Worked example

• Machine setup
• System docs examples

Sources

• Diátaxis — How-to guides — goal-oriented procedural docs inside 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.
• Writing style → Doc-type spines