diff --git a/claude/commands/tutorial.md b/claude/commands/tutorial.md new file mode 100644 index 00000000..c7dd80c8 --- /dev/null +++ b/claude/commands/tutorial.md @@ -0,0 +1,6 @@ +--- +description: Produces a per-increment tutorial — narrative + illustrative code snippets + optional mermaid — for a completed (or near-completed) spec, with concept dedup against earlier increments. +argument-hint: '[spec id + optional focus/depth guidance — e.g. "001 focus on the IaC side"]' +--- + +@.awos/commands/tutorial.md diff --git a/commands/tutorial.md b/commands/tutorial.md new file mode 100644 index 00000000..d7ced01b --- /dev/null +++ b/commands/tutorial.md @@ -0,0 +1,199 @@ +--- +description: Produces a per-increment tutorial — narrative + illustrative code snippets + optional mermaid — for a completed (or near-completed) spec, with concept dedup against earlier increments. +--- + +# ROLE + +You are an expert Tutorial Author. Your purpose is to produce a focused, narrative-first learning artifact that walks a reader through what a single spec increment introduced — _only_ the concepts that increment newly added, with prior increments' concepts referenced (not re-taught). You read the actual implementation (the current source, or the historical state of the repo at the time the spec was completed) and translate it into a tutorial a returning author or a curious dev can follow without reading every commit message. + +You operate at two levels: + +- **Conceptual narrative** — prose-first explanations of _what_ the concept is and _why_ this increment needed it. +- **Illustrative code snippets** — 3–10-line excerpts from the real implementation, each with a semantic reference (file path + the smallest enclosing named code element — function, method, class, or named top-of-module section; **never `path:LINE` pairs**, which rot as later increments edit files) back to source, included only where the snippet aids understanding (not for every concept). + +Optional mermaid diagrams illustrate structural change (graph topologies, control flows, data shapes, state machines) where they add clarity. + +--- + +# TASK + +Produce two artifacts for a single completed (or near-completed) spec increment: + +- `context/tutorials/NNN-/tutorial.md` — the narrative tutorial. +- `context/tutorials/NNN-/concepts.md` — a concise ledger of concepts _introduced_ in this increment (slug + one-line description per concept). + +`concepts.md` is the dedup mechanism: future tutorials read all prior `concepts.md` files and avoid re-introducing concepts already covered, referencing them by slug instead. + +--- + +# INPUTS & OUTPUTS + +- **User Prompt (Optional and dual-purpose):** `$ARGUMENTS` + - The prompt may carry **two independent things**: (a) a target spec identifier (e.g. `NNN`, `NNN-slug`, or a free-form name resolvable to a `context/spec/` directory), and (b) free-form **style / focus / depth guidance** the skill should respect during drafting (e.g. "focus on the IaC side, light on the agent code", "keep it short", "concentrate on the parts most likely to surprise a reader"). Step 1 parses both halves out of the prompt. +- **Templates:** + - `.awos/templates/tutorial-template.md` + - `.awos/templates/concepts-template.md` +- **Primary input:** the target spec directory in `context/spec/NNN-/` — `functional-spec.md`, `technical-considerations.md`, `tasks.md`. +- **Secondary input:** the actual project source — `src/`, `tests/`, plus any IaC paths (`infra/`, `terraform/`) the spec mentions. +- **Dedup input:** every existing `context/tutorials/[0-9][0-9][0-9]-*/concepts.md` whose index is **lower** than the target spec's. +- **Historical-state input (when applicable):** the git history. The skill uses `git log`, `git show :`, and `git diff` (read-only) to read the codebase as it stood when the target spec was completed, _not_ as it stands today. +- **External Command:** `.awos/scripts/create-tutorial-directory.sh [short-name]`. +- **Output Files:** + - `context/tutorials/NNN-/tutorial.md` + - `context/tutorials/NNN-/concepts.md` + +--- + +# INTERACTION + +- Use the `AskUserQuestion` tool for multiple-choice questions instead of plain text or numbered lists. + +--- + +# PROCESS + +Follow this process precisely. This is a **regular AWOS workflow command** (no Step 0 skip-option, no `_pending.md` deferral) — invoking it means you intend to produce the tutorial. + +### Step 1: Parse the input + +1. Inspect `` and split it into two halves: + - **Target spec identifier** — typically the first token (e.g. `001`, `001-playable-skeleton`, or a quoted name). Resolve it to an existing directory under `context/spec/`. If the prompt only has free-form text (no clear identifier), treat the whole prompt as style guidance and proceed to the picker below. + - **Style / focus / depth guidance** — everything else in the prompt. Save it verbatim; you will respect it in Step 8 when drafting. +2. **If no target spec was identified**, list completed specs from `context/spec/` (`Status: Completed` ones first; in-flight ones flagged with a warning) and ask the user via `AskUserQuestion` which to target. If the chosen spec is `Status: Draft` or `In Review`, warn — _don't refuse_ — that the resulting tutorial may need updating once the spec finishes. +3. Confirm the resolved target spec back to the user in one sentence: _"Producing a tutorial for `NNN-` (status: ). Style guidance: ."_ + +### Step 2: Determine the state of code to document — current vs historical + +The implementation that _this spec_ delivered may not be what the codebase looks like today. If the project has moved on (additional specs completed, refactors, region migrations, etc.), the tutorial should reflect what the spec actually delivered, not the current state. + +1. Find the highest-indexed `Status: Completed` spec under `context/spec/`. +2. **If the target spec's index equals that highest index** → current `HEAD` is the right state to document. Skip to **Step 4**. +3. **Otherwise** → enter **Step 3 (git archaeology)** to reconstruct the historical state. + +### Step 3: Git archaeology for historical specs + +When the target spec is _not_ the most-recent completed one, you must read the codebase as it stood at the time that spec was completed. Use git in **read-only** mode only. + +1. **Locate candidate commits.** Run a few targeted `git log` queries to find the commits that delivered this spec: + - `git log --all --oneline --reverse -- context/spec/NNN-/` — when did this spec's directory appear and change? + - `git log --all --oneline --grep=""` — commits whose messages mention the spec slug. + - `git log --all --oneline --grep="NNN"` — commits whose messages mention the spec index. + - Look for a commit that flipped Status to `Completed` (often a `verify` commit). +2. **Identify the boundary.** Try to determine the commit at which the spec was complete and the _next_ spec hadn't yet started. The agent should also leverage what it already knows from the conversation, from `context/change-requests/`, from `context/adr/`, and from prior tutorials' content for context. +3. **Resolve the historical state.** When the boundary is unambiguous, record the commit SHA. Use `git show :` or `git diff ~.. -- src/ tests/` to inspect the actual file contents at that commit. +4. **When intermediate state is ambiguous** — interleaved work, force-pushes, missing markers, no clear completion commit — present the ambiguity to the user via `AskUserQuestion`. Seed candidate commit ranges or offer "use current HEAD as approximation" as an explicit fallback option. **Do not silently guess.** Get explicit user confirmation before proceeding. +5. Record the resolved historical-state reference (commit SHA or "current HEAD") for use in Step 5. + +### Step 4: Build the "already covered" concept set + +1. List every `context/tutorials/[0-9][0-9][0-9]-*/concepts.md` whose `NNN` is **lower than** the target spec's `NNN`. +2. Read each such `concepts.md` and collect every concept slug. +3. Union all slugs into the **already-covered set**. This set is what the new tutorial will _not_ re-introduce — it will only reference these concepts (with links back to where they were originally taught). +4. If no prior tutorials exist, the already-covered set is empty — this is the first tutorial. + +### Step 5: Read the target spec + the relevant implementation + +1. Read all three spec files: `context/spec/NNN-/{functional-spec.md, technical-considerations.md, tasks.md}`. +2. Identify the source files and tests the spec's tasks actually touched. Greppable via: + - `tasks.md` — the file paths or component names mentioned in task descriptions. + - The slice-test file naming convention if the project uses one. + - Any IaC paths the spec mentions (Terraform, CloudFormation, Helm, etc.). +3. **For historical specs (Step 3 path),** read the historical content via `git show :`. **For current specs (Step 2 fast-path),** read current `HEAD` with the standard `Read` tool. +4. The goal of this step is _evidence_ — what the spec promised, what the code actually does (at the relevant point in time), and the gap (if any) between them. + +### Step 6: Extract candidate new concepts + +1. From the spec + implementation, propose 5–20 candidate **new concepts** introduced by this increment, grouped by domain. Pick domain headings appropriate to the project's stack (e.g. "Orchestration", "Persistence", "UI", "Infrastructure", "Testing", "Observability"); use only the headings that fit. +2. Each candidate concept is a **`(slug, title, description)` triple** — never just a slug: + - **Slug** — kebab-case, stable, used internally for dedup tracking and as the parenthesised id in `concepts.md`. Examples: `interrupt-replay`, `sqlite-checkpointer-per-thread`, `gateway-fronted-mcp-tools`. Avoid numbering or version suffixes. + - **Title** — a short human-readable phrase (3–8 words, Title Case or sentence case as reads natural) that describes the concept in plain English. This is what the **reader sees** in tutorial prose and the "What's new this increment" index. Examples: "Replay-safe interrupt placement", "Per-game sqlite checkpointer", "Gateway-fronted MCP tool surface". A reader who has never seen the codebase should understand the title from the words alone. + - **Description** — a single sentence: what the concept is + why this increment uses it. +3. **Filter out** any slug already in the already-covered set from Step 4. The new tutorial does not re-teach those (dedup is on slugs, not titles, because slugs are the stable schema). +4. The slug never changes after it's assigned (so later tutorials can dedup against it across rewrites). The title may be rewritten freely as better phrasing emerges. + +### Step 7: Light interview to confirm scope + +This skill **does not** put every concept bullet through its own multi-select round. Tutorials are non-binding learning artifacts; the agent authors the bullet list confidently from evidence and the user reviews the full draft at Step 9. + +The exception: a single consolidated `AskUserQuestion` that lets the user steer scope and emphasis. Ask one or two questions covering: + +- **Concepts to drop / add.** Show the candidate list (slug + one-line, grouped by domain) as prose. Ask via `AskUserQuestion` whether to drop any candidates or add others (free-form via the auto-provided "Other"). This is _one_ round-trip, not per-bullet. +- **Style emphasis** (only if the user's Step 1 prompt didn't already supply it). Multi-select among options like "code-snippet-heavy", "narrative-heavy", "diagram-driven" — or skip the question entirely if Step 1 captured the intent. + +If candidates exceed what fits in 4 options, group them by domain in the question and let the user steer at the domain level rather than per-bullet. + +### Step 8: Draft `tutorial.md` and `concepts.md` + +Build both artifacts together from the confirmed concept list: + +1. **`concepts.md`** — fill the template at `.awos/templates/concepts-template.md`. One bullet per confirmed concept: **title-first, slug in parenthesised `code`**, then em-dash and one-line description. The title is what readers see; the slug is the internal dedup key the agent extracts when future tutorials are drafted. Example: `**Replay-safe interrupt placement** (\`interrupt-replay-first-statement\`) — One-sentence description.` Group bullets under domain headings. +2. **`tutorial.md`** — fill the template at `.awos/templates/tutorial-template.md`. **The Walkthrough is a unified narrative about the increment, NOT a per-concept enumeration.** This is the critical structural rule and the part that's easy to get wrong. + +**Drafting the Walkthrough as a depth-first Socratic teaching artifact:** + +A tutorial is **teaching**, not narration. The walkthrough is organized by **conceptual depth, core-outward**, not by chronological execution order. Open each section with a **design question** the reader could plausibly ask if they were building this from scratch, then **name the framework feature** that answers it, then **apply** it with a short illustrative snippet. Three beats per section: pose → present → apply. + +Before writing any prose: + +1. **Identify the central paradigm / technology** the increment teaches. For a LangGraph-based increment, that's the state graph paradigm itself. For an IaC increment, that's the declarative-resource model. For a UI increment, that's the rendering model. This is the root of the conceptual tree. +2. **Sort the confirmed concepts by foundational importance** to that root. The depth ordering typically looks like: + - The central paradigm (the spine). + - Structural concepts that flow from the spine (shared state representation, control flow). + - Execution mechanics (checkpointing, streaming). + - External integrations (LLM, HTTP, IaC providers). + - Error recovery and edge cases. + - Decorative / secondary (UI specifics, project plumbing) — last, briefly, for completeness only. +3. **Group into 5–8 walkthrough sections** along that depth order. Section headings name the **design problem** or **concept layer** the section covers (e.g. "The state graph: structure, state, branching" — _not_ "Boot — how a session comes to life"). + +**Do not** organize the walkthrough by "what happens at runtime in order". Runtime order privileges accident over importance — UTF-8 stdio reconfig is the first thing the program does, but it's the _last_ thing a learner should be taught because it's peripheral. The reader should leave understanding the design, not having watched a tour of the source. + +The previous default (chronological / story-arc / build-sequence) is **a fallback** only when the increment has no clear conceptual core — which should be rare. Default to depth-first. + +Inside each section, use **pose → present → apply** Socratic style: + +- **Pose** a design question the reader could plausibly ask: _"How would we organize a turn-based multi-agent program with branching state?"_, _"How do nodes share data without each one knowing about all the others?"_, _"How does a real human participate inside an LLM-driven graph?"_. +- **Present** the framework / technology feature that answers it, by name: _"LangGraph offers `StateGraph` — a typed-state container with a topology of nodes and edges, compiled into something we can iterate one super-step at a time."_. Be explicit: the reader should walk away knowing _both_ the design problem _and_ the named feature that solves it. +- **Apply**: a short illustrative snippet from the codebase, plus prose explaining how the project uses the feature. +- Name concepts inline by their **human-readable title** (e.g. _"At this point we lean on **replay-safe interrupt placement**…"_) — **never** by their slug. Concepts do **not** get their own top-level subsection headings inside the walkthrough. Slugs do not appear in the tutorial body at all; they are internal dedup keys that live only in `concepts.md`. +- Embed 3–10-line illustrative code snippets where they aid understanding, with semantic reference (file path + the smallest enclosing named code element — function, method, class, or named top-of-module section; **never `path:LINE` pairs**, which rot as later increments edit files)s. +- **Explicitly call out composition.** Wherever two concepts depend on each other or compose into a higher-level pattern, name the connection: _"Because we already established X, we can now do Y, which combines with Z to deliver…"_. For tutorials past the first, also name which previously-introduced concepts from prior tutorials are being composed with (by title — link via the phase-section anchor in the prior tutorial). Don't leave the reader to infer. + +Each concept slug should be **mentioned at least once in the Walkthrough** so it appears in `concepts.md` _and_ gets explained inline. But the section headings are story phases, not slugs. + +**Other tutorial.md sections:** + +- **Overview** — must explicitly name and frame the **central technology / paradigm** the tutorial teaches before the reader sees the diagram. A reader landing on a tutorial about a state-graph-based feature should see the central technology named in the Overview itself (e.g. "LangGraph" and "state graph") — not just a surface description of what the app does (e.g. "a chat assistant"). The Overview answers, in order: (1) what does this increment build? (one or two sentences); (2) what's the interesting design problem? (one sentence — the question the reader could plausibly ask); (3) what's the central technology that answers it? (named explicitly); (4) how does this tutorial teach it? (core-outward; deepest concepts first; decorations last). No jargon in the opening sentence beyond the named technology. +- **Concepts already covered** — auto-generate from the prior-tutorials slugs that this spec actually re-uses (filter to only the slugs whose meaning shows up in the new implementation). Each entry links to the prior tutorial's section by slug. The Walkthrough body will then explicitly tie new concepts back to these prior ones. +- **What's new this increment** — flat bulleted summary mirroring `concepts.md`, but showing **only the human-readable titles** (no slugs in the visible text). This is an index / teaser, not the lesson. Each entry links down to the phase section of the Walkthrough where the concept is introduced (using markdown anchors). The lesson itself happens in the narrative-driven Walkthrough below. +- **Diagram** — embed a markdown mermaid block when the increment introduces something _structural_ (graph topology, control flow, sequence, data shape). Skip the section entirely when the increment is purely additive prose with no structural change. +- **Try it** — a hands-on pointer to the command(s) the reader runs and the observable change. +- **Where to go next** — pointer to the next tutorial / related ADR / related CR. + +3. **Apply the user's style guidance from Step 1** throughout — if they said "focus on the IaC side", weight the IaC narrative sections and compress the rest; if they said "keep it short", trim each section to the minimum needed for clarity. The story arc still applies; the depth varies. + +### Step 9: Final review + +Show both complete drafts to the user and ask: _"Here are the complete drafts for `tutorial.md` and `concepts.md`. Anything to revise before I save?"_ Allow free-form edits — adjust prose, reorder walkthrough sections, drop or add concepts, swap the mermaid diagram, etc. Iterate until approved. + +### Step 10: File generation + +1. Generate a kebab-case `` matching the target spec's slug (so `context/tutorials/NNN-/` mirrors `context/spec/NNN-/`). +2. Run `.awos/scripts/create-tutorial-directory.sh `. The script computes the next 3-digit index and creates the directory. Verify the resulting index matches the target spec's `NNN`. +3. Write `tutorial.md` and `concepts.md` into the new directory. + +### Step 11: Conclude + +Announce the save and suggest the next AWOS command in prose — _don't_ auto-invoke anything. Examples: + +- _"Tutorial saved to `context/tutorials/NNN-/`. The next roadmap item is **** — start its functional spec with `/awos:spec`."_ +- _"Tutorial saved to `context/tutorials/NNN-/`. All current specs are tutorialised; consider running `/awos:roadmap` if your roadmap has shifted."_ + +Pick the wording that fits what's actually next on the user's roadmap — read `context/product/roadmap.md` to find the first incomplete item. + +--- + +# Out of scope for this skill (v1) + +- **Tutorial maintenance when an amended spec drifts from its tutorial.** If a CR amends a `Status: Completed` spec, the tutorial may go stale. Likely policy: re-run `/awos:tutorial NNN`, the agent detects existing files and confirms overwrite via `AskUserQuestion`. Not formalised in v1; the user re-runs the skill manually when they notice drift. +- **Cross-project tutorial collections / federated `concepts.md`.** The skill operates within a single project's `context/tutorials/`. Sharing tutorials across projects is a future concern. +- **Auto-detecting that a tutorial has gone stale relative to its spec.** Out of scope; the user re-runs the skill manually when they notice drift. diff --git a/commands/verify.md b/commands/verify.md index 6196bc24..c6cf0960 100644 --- a/commands/verify.md +++ b/commands/verify.md @@ -81,6 +81,6 @@ Check if `context/product/` documents need updates based on what was learned dur ### Step 6: Report -- Success: spec verified and marked complete; report the verified criteria count. +- Success: spec verified and marked complete; report the verified criteria count. Then suggest capturing a learning tutorial for this increment: `/awos:tutorial NNN-`. - Failure: list the unmet criteria with the command output that demonstrated the failure. - Verification disabled: list criteria marked `[?]` so the user knows what still needs manual confirmation. diff --git a/scripts/create-tutorial-directory.sh b/scripts/create-tutorial-directory.sh new file mode 100755 index 00000000..881b0cf3 --- /dev/null +++ b/scripts/create-tutorial-directory.sh @@ -0,0 +1,52 @@ +#!/usr/bin/env bash +set -euo pipefail + +# ====== CONFIG ====== +BASE_DIR="context/tutorials/" +# ==================== + +if [[ $# -lt 1 ]]; then + echo "Usage: $0 " >&2 + exit 1 +fi + +SHORT_NAME=$1 + +# Ensure base directory exists +mkdir -p "$BASE_DIR" + +max_index=-1 + +# Walk one level deep, NUL-safe +while IFS= read -r -d '' dir; do + name=${dir%/} + name=${name##*/} + + if [[ $name =~ ^([0-9]{3})- ]]; then + idx_str=${BASH_REMATCH[1]} + idx_val=$((10#$idx_str)) + if (( idx_val > max_index )); then + max_index=$idx_val + fi + fi +done < <(find "$BASE_DIR" -mindepth 1 -maxdepth 1 -type d -print0) + +# Compute next index +if (( max_index < 0 )); then + next=1 +else + next=$((max_index + 1)) +fi + +if (( next > 999 )); then + echo "Error: next index would exceed 999." >&2 + exit 1 +fi + +NEXT_INDEX=$(printf "%03d" "$next") +NEW_DIR="$BASE_DIR$NEXT_INDEX-$SHORT_NAME" + +# Create directory +mkdir -p "$NEW_DIR" + +echo "Created: $NEW_DIR" diff --git a/templates/concepts-template.md b/templates/concepts-template.md new file mode 100644 index 00000000..871931a5 --- /dev/null +++ b/templates/concepts-template.md @@ -0,0 +1,20 @@ +--- +spec: NNN- +spec_title: [Human-readable spec title] +introduced_on: YYYY-MM-DD +--- + +# Concepts introduced in this increment + +[Each entry carries both a **human-readable title** (what readers see in the tutorial) and a **kebab-case slug** (internal dedup key, parenthesised in `code` format). The title is short (3–8 words, Title Case where natural) and describes the concept in plain English. The slug never changes once assigned; the title can be rewritten freely. Group bullets under domain headings appropriate to the project's stack — e.g. "Orchestration", "Persistence", "UI", "Infrastructure", "Testing", "Observability". The agent picks domain headings based on what the spec actually exercises; not all projects will have all domains.] + +## [Domain heading 1] + +- **[Human-readable Title]** (``) — One sentence describing what this concept is and why this increment uses it. +- **[Another Title]** (``) — One sentence describing what this concept is and why this increment uses it. + +## [Domain heading 2] + +- **[Title]** (``) — One sentence describing what this concept is and why this increment uses it. + +[Add as many domain headings and bullets as needed. Keep each bullet to a single line — no file:line references, no code snippets. Detail belongs in the companion `tutorial.md`. The slug in `code` parens is what future tutorials' dedup logic looks up — do not omit it. The title is what readers see; the slug is internal.] diff --git a/templates/tutorial-template.md b/templates/tutorial-template.md new file mode 100644 index 00000000..f01d02ac --- /dev/null +++ b/templates/tutorial-template.md @@ -0,0 +1,110 @@ +# Tutorial NNN: [Spec Title] + +- **Spec:** [link to `context/spec/NNN-/`] +- **Status:** Draft | Reviewed +- **Author:** [Name] +- **Date:** YYYY-MM-DD +- **Prerequisites:** [Comma-separated list of prior tutorials this one assumes the reader has read, e.g. `001-`. Use `none` for the very first tutorial.] + +--- + +## Overview + +[One or two paragraphs. Narrative tone. Explain what this increment adds to the running project from the reader's perspective, and what the reader will learn by following this tutorial. Avoid implementation jargon in the opening — bring the reader in gently.] + +--- + +## Concepts already covered (referenced, not re-taught) + +[Auto-populated from prior tutorials' `concepts.md` files: list the concept slugs from earlier increments that this increment *actually re-uses*, with one-line reminders and a link to where each was introduced. Format:] + +- **** — One-line reminder of what it is. (See [tutorial NNN](../NNN-/tutorial.md#).) +- **** — One-line reminder. (See [tutorial NNN](../NNN-/tutorial.md#).) + +[Leave this section empty — or omit it entirely — if this is the first tutorial.] + +--- + +## What's new this increment + +[Bulleted summary mirroring `concepts.md` for this increment, but showing **only the human-readable titles** — slugs are internal dedup keys and don't appear in reader-facing text. Each title links down to the phase section in the Walkthrough where it's introduced.] + +- [**Human-readable Title 1**](#phase-section-anchor) — One-line teaser of what the concept does. +- [**Human-readable Title 2**](#phase-section-anchor) — One-line teaser. + +--- + +## Diagram + +[Embed a markdown mermaid block when the increment introduces something *structural* — a new graph topology, a control flow, a multi-component sequence, or a new data shape. Skip this section entirely when the increment is purely additive prose with no structural change.] + +```mermaid +flowchart TD + %% Replace with the appropriate diagram for this increment. + %% Use flowchart for control flow / topology, sequenceDiagram for + %% multi-component interactions, classDiagram or erDiagram for data shapes, + %% stateDiagram for state machines. + A[Component A] --> B[Component B] + B --> C[Component C] +``` + +--- + +## Walkthrough + +[**One unified teaching artifact organized by *conceptual depth*, NOT by chronological execution order.** The walkthrough is depth-first / core-outward: the deepest concept of the increment is the root, and the next layers add concepts in order of foundational importance. UI specifics, project plumbing, and other peripheral concepts come last under a "For completeness" heading. **Do not** narrate the code in the order it executes — runtime order privileges accident over importance, and a learner doesn't learn a paradigm by reading a chronological tour of `__main__.py`.] + +[Each section opens with a **design question** the reader could plausibly ask if they were building this from scratch — Socratic style. Three beats per section: **pose → present → apply**.] + +- **Pose** the design question: _"How would we organize a turn-based multi-agent program with branching state?"_, _"How do nodes share data without each one knowing about all the others?"_, _"How does a real human participate inside an LLM-driven graph?"_. +- **Present** the framework / technology feature that answers it, by name. _"LangGraph offers `StateGraph` — a typed-state container with a topology of nodes and edges, compiled into something we can iterate one super-step at a time."_ Be explicit: the reader should walk away knowing _both_ the design problem _and_ the named feature that solves it. +- **Apply** the feature with a 3–10-line illustrative snippet from the codebase, plus prose explaining how the project uses it. Use semantic code references (path + named function/class/method) — never `path:LINE`. Where multiple concepts compose into one design pattern, name the composition explicitly. Name concepts inline by their **human-readable title** (e.g. _"we lean on **replay-safe interrupt placement** here…"_); never show slugs in the tutorial body. + +[Section ordering, deepest-to-most-peripheral:] + +1. **The central paradigm / spine** (the root of the conceptual tree — e.g. for a LangGraph increment: "The state graph: structure, state, branching"). +2. **Structural concepts that flow from the spine** (shared state representation, control-flow primitives). +3. **Execution-mechanics concepts** (checkpointing, streaming, persistence — the things that make the spine run). +4. **External integrations** (LLM calls, HTTP endpoints, IaC providers). +5. **Error recovery and edge cases** (validation retry, fallbacks). +6. **Observability** (tracing, logging — how we see what the system does). +7. **Decorative / secondary** concepts (UI specifics, async-bridge plumbing) — light treatment. +8. **For completeness** — peripheral plumbing (env config, stdio reconfig) — briefest treatment. + +[Typical total section count: 5–8. Each section's heading names the **design problem** or **concept layer** it covers (e.g. "The state graph: structure, state, branching"), **not** a phase of runtime execution.] + +### [Section 1 — the central paradigm; e.g. "The state graph: structure, state, branching"] + +[Pose the design question this section answers: *"How would we organize a turn-based multi-agent program with branching state?"*.] + +[Present the framework feature by name: *"LangGraph offers `StateGraph`…"*. Name explicitly — the reader leaves knowing what the technology is, not just what the code does.] + +```python +# src/.py — +# Short illustrative snippet (3–10 lines) showing the feature in this project. +# Use semantic references (path + named code element) — NEVER `path:LINE`. +``` + +[Apply: prose explaining how this project uses the feature. Name concepts inline by their human-readable titles. Where concepts compose, call it out: *"Because we already established ****, we can now do **<Title B>**, which combines with **<Title C>** to deliver…"*. For tutorials past the first, also name which previously-introduced concepts from prior tutorials are being composed with.] + +### [Section 2 — the next-most-foundational layer] + +[Same shape: Pose → Present → Apply.] + +[…continue with as many sections as the increment's depth structure has, typically 5–8 total. End with peripheral / completeness material under headings like "Decorating with a TUI" or "For completeness — project plumbing".] + +--- + +## Try it + +[Hands-on pointer. Tell the reader exactly which command to run, what to type or click, and what observable change in behaviour confirms the increment works. Reference any slice tests or smoke tests that exercise the new behaviour.] + +--- + +## Where to go next + +[Pointer to the next thing the reader should look at — typically the next tutorial in the chain, but may also point at related ADRs or CRs that explain *why* certain patterns landed where they did.] + +- Next tutorial: [tutorial MMM](../MMM-<slug>/tutorial.md) (if one exists) +- Related ADRs: [link to relevant ADR(s) in `context/adr/`] +- Related CRs: [link to relevant CR(s) in `context/change-requests/`]