From bb0d472bd0699f9374e8ab0305847e313e575b5e Mon Sep 17 00:00:00 2001 From: "R. Mark Sharp" Date: Sat, 20 Jun 2026 17:12:05 -0500 Subject: [PATCH 1/7] docs(tutorials): add sample todo-CLI practice project (P1) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Bundled, throwaway stdlib-only todo CLI that the tutorial series runs real methodology sessions against. Ships WITHOUT methodology files — installing the framework onto it is Tutorial 1's exercise. - todo.py: add/list core kept I/O-light and print-free for direct testing; intentionally missing `done` command (F1 = Tutorial 2's first feature) - test_todo.py: 7 unittest cases, green under both pytest and `python -m unittest` (the project's build equivalent, zero extra deps) - BACKLOG.md: seed features (F1 first) + planted rough edges (B1) for Tutorial 5 - README.md + .gitignore Part of tutorial-series plan §9 P1 (scaffolding). No tutorial content yet. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/tutorials/sample-project/.gitignore | 4 + docs/tutorials/sample-project/BACKLOG.md | 36 +++++++ docs/tutorials/sample-project/README.md | 39 +++++++ docs/tutorials/sample-project/test_todo.py | 70 +++++++++++++ docs/tutorials/sample-project/todo.py | 113 +++++++++++++++++++++ 5 files changed, 262 insertions(+) create mode 100644 docs/tutorials/sample-project/.gitignore create mode 100644 docs/tutorials/sample-project/BACKLOG.md create mode 100644 docs/tutorials/sample-project/README.md create mode 100644 docs/tutorials/sample-project/test_todo.py create mode 100644 docs/tutorials/sample-project/todo.py diff --git a/docs/tutorials/sample-project/.gitignore b/docs/tutorials/sample-project/.gitignore new file mode 100644 index 00000000..b47fc772 --- /dev/null +++ b/docs/tutorials/sample-project/.gitignore @@ -0,0 +1,4 @@ +# Runtime + test artifacts generated while practicing — never commit these. +todos.json +__pycache__/ +.pytest_cache/ diff --git a/docs/tutorials/sample-project/BACKLOG.md b/docs/tutorials/sample-project/BACKLOG.md new file mode 100644 index 00000000..df5b8b96 --- /dev/null +++ b/docs/tutorials/sample-project/BACKLOG.md @@ -0,0 +1,36 @@ +# Sample Project — Backlog + +This backlog exists to give the methodology tutorials something real to work on. It is +deliberately small and a little rough. Items are ordered so the **first feature is the one +Tutorial 2 builds end-to-end**. + +> When you bootstrap the framework onto this project in Tutorial 1, this file becomes your +> `BACKLOG.md`. The methodology's "1 deliverable per session" rule means you pick **one** +> item, take it through all six phases, and stop. + +## Features + +| id | Feature | Notes | +|----|---------|-------| +| F1 | `todo done ` — mark a task complete | **Start here (Tutorial 2).** The data model already has a `done` flag; only the command is missing. Small, vertical, testable. | +| F2 | `todo rm ` — delete a task | Decide what happens to ids after a delete (see the `test_add_reuses_max_id_plus_one_after_gaps` test). | +| F3 | `todo done ` should be reversible (`undo`) | Roadmap. | +| F4 | Due dates (`--due`) and an overdue marker in `list` | Roadmap; bigger than one session — a candidate to split. | + +## Known rough edges (good cautionary cases) + +| id | Issue | Why it's here | +|----|-------|---------------| +| B1 | `add` accepts empty/whitespace text | `add_todo` does no validation (see the NOTE in `todo.py`). It is tempting to "just fix this real quick" while building F1 — doing so is scope creep, and **Tutorial 5** uses it as a worked example of the urge to break the "1 deliverable" rule. Fix it as its **own** session, with its own test. | +| B2 | No confirmation before overwriting `todos.json` | Latent data-loss risk; not urgent. | + +## How to verify your work + +This project's **build equivalent** is its test suite. After any change, both of these must stay green: + +```sh +python -m pytest # the documented runner +python -m unittest # stdlib fallback, no dependencies +``` + +A new feature is not "done" until it has a test that fails before your change and passes after. diff --git a/docs/tutorials/sample-project/README.md b/docs/tutorials/sample-project/README.md new file mode 100644 index 00000000..fe1029f3 --- /dev/null +++ b/docs/tutorials/sample-project/README.md @@ -0,0 +1,39 @@ +# Sample Project — a tiny todo CLI + +This is the **practice substrate** for the methodology tutorials. It is intentionally small, +plain, and throwaway: a stdlib-only Python todo-list CLI with a real test suite and a short +[backlog](BACKLOG.md). You will run real methodology sessions against it. + +It ships **without** any methodology files (no `SESSION_RUNNER.md`, no `CLAUDE.md`, no +`BACKLOG.md`-as-task-tracker). Installing the framework onto this project is exactly what you +do in **Tutorial 1** — see [`../README.md`](../README.md) for the series index. + +## Try it + +```sh +cd docs/tutorials/sample-project + +python3 todo.py add "write the report" +python3 todo.py add "submit the report" +python3 todo.py list +``` + +State is stored in `todos.json` in the current directory (override with `--file PATH` or the +`TODO_STORE` env var). `todos.json` is throwaway — delete it any time. + +## The build equivalent (run this after every change) + +```sh +python -m pytest # the runner the tutorials document +python -m unittest # stdlib fallback — zero dependencies +``` + +Both should report all tests passing. In methodology terms this is your *build equivalent*: +green tests are the gate, not "it ran once on my machine." + +## What's deliberately missing + +The CLI has `add` and `list` but **no way to mark a task done** — even though each task already +carries a `done` flag. Wiring up `todo done ` is the first feature you build, end-to-end, in +Tutorial 2. The [backlog](BACKLOG.md) lists the rest, including a couple of rough edges that +Tutorial 5 uses as cautionary cases. Don't fix everything at once — that's the whole point. diff --git a/docs/tutorials/sample-project/test_todo.py b/docs/tutorials/sample-project/test_todo.py new file mode 100644 index 00000000..dc564198 --- /dev/null +++ b/docs/tutorials/sample-project/test_todo.py @@ -0,0 +1,70 @@ +"""Tests for the sample todo CLI — the project's "build equivalent". + +Written with stdlib `unittest` so they pass under BOTH: + + python -m pytest # the runner the tutorials document + python -m unittest # zero extra dependencies + +Run either from inside docs/tutorials/sample-project/. +""" +import json +import tempfile +import unittest +from pathlib import Path + +import todo + + +class CoreTests(unittest.TestCase): + def test_add_assigns_incrementing_ids(self): + todos: list[dict] = [] + first = todo.add_todo(todos, "write the report") + second = todo.add_todo(todos, "submit the report") + self.assertEqual(first["id"], 1) + self.assertEqual(second["id"], 2) + self.assertFalse(first["done"]) + self.assertEqual(len(todos), 2) + + def test_add_reuses_max_id_plus_one_after_gaps(self): + # Ids continue from the current max, not the count — survives future deletes. + todos = [{"id": 5, "text": "old", "done": True}] + new = todo.add_todo(todos, "new") + self.assertEqual(new["id"], 6) + + def test_render_empty_is_friendly(self): + self.assertIn("no todos yet", todo.render([])) + + def test_render_marks_done_and_pending(self): + out = todo.render([ + {"id": 1, "text": "done thing", "done": True}, + {"id": 2, "text": "pending thing", "done": False}, + ]) + self.assertIn("[x] done thing", out) + self.assertIn("[ ] pending thing", out) + + def test_save_then_load_round_trips(self): + with tempfile.TemporaryDirectory() as d: + store = Path(d) / "todos.json" + todos = [{"id": 1, "text": "persisted", "done": False}] + todo.save_todos(store, todos) + self.assertEqual(todo.load_todos(store), todos) + # File is valid, human-readable JSON. + self.assertEqual(json.loads(store.read_text())[0]["text"], "persisted") + + def test_load_missing_store_returns_empty(self): + with tempfile.TemporaryDirectory() as d: + self.assertEqual(todo.load_todos(Path(d) / "nope.json"), []) + + +class CliTests(unittest.TestCase): + def test_add_then_list_via_main(self): + with tempfile.TemporaryDirectory() as d: + store = str(Path(d) / "todos.json") + self.assertEqual(todo.main(["--file", store, "add", "buy milk"]), 0) + data = json.loads(Path(store).read_text()) + self.assertEqual(data[0]["text"], "buy milk") + self.assertEqual(todo.main(["--file", store, "list"]), 0) + + +if __name__ == "__main__": + unittest.main() diff --git a/docs/tutorials/sample-project/todo.py b/docs/tutorials/sample-project/todo.py new file mode 100644 index 00000000..8be9d43d --- /dev/null +++ b/docs/tutorials/sample-project/todo.py @@ -0,0 +1,113 @@ +#!/usr/bin/env python3 +"""todo — a deliberately tiny todo-list CLI, the methodology tutorials' sample project. + +This is throwaway practice code. It exists so a learner can run a *real* methodology +session against it: it has a genuine build equivalent (`python -m pytest` / `python -m +unittest`), a believable backlog of features and bugs (see BACKLOG.md), and a couple of +rough edges that make good cautionary cases. + +Design notes for the tutorials: +- The *core* (load/save/add/render) is kept free of I/O-on-import and free of `print`, + so tests can call it directly without spawning a subprocess. +- `main()` is a thin argument-dispatch shell around the core. +- It is intentionally INCOMPLETE. The data model already carries a `done` flag, but there + is no command to set it — wiring up `todo done ` is the first feature a learner + builds in Tutorial 2. Do not "fix" that here; it is the worked example. + +Stdlib only. No third-party dependencies. Python 3.8+. +""" +from __future__ import annotations + +import argparse +import json +import os +import sys +from pathlib import Path + +DEFAULT_STORE = "todos.json" + + +# --- core (pure-ish; no printing, easy to test) ------------------------------ + +def load_todos(store: Path) -> list[dict]: + """Return the list of todos from `store`, or [] if it does not exist yet.""" + if not store.exists(): + return [] + return json.loads(store.read_text(encoding="utf-8")) + + +def save_todos(store: Path, todos: list[dict]) -> None: + """Persist `todos` to `store` as pretty-printed JSON.""" + store.write_text(json.dumps(todos, indent=2) + "\n", encoding="utf-8") + + +def add_todo(todos: list[dict], text: str) -> dict: + """Append a new todo with the next id and return it. + + NOTE (BACKLOG #B1): `text` is not validated — an empty string is accepted and + produces a blank, un-actionable task. Catching the urge to "just quickly fix this + inline" while doing something else is one of Tutorial 5's cautionary cases. + """ + next_id = max((t["id"] for t in todos), default=0) + 1 + todo = {"id": next_id, "text": text, "done": False} + todos.append(todo) + return todo + + +def render(todos: list[dict]) -> str: + """Return the human-readable listing (newline-joined; no trailing newline).""" + if not todos: + return "(no todos yet — add one with: todo add \"your task\")" + lines = [] + for t in todos: + box = "[x]" if t["done"] else "[ ]" + lines.append(f"{t['id']:>3} {box} {t['text']}") + return "\n".join(lines) + + +# --- cli shell --------------------------------------------------------------- + +def _store_path(args: argparse.Namespace) -> Path: + """Resolve the store path: --file flag wins, else $TODO_STORE, else ./todos.json.""" + return Path(args.file or os.environ.get("TODO_STORE", DEFAULT_STORE)) + + +def cmd_add(args: argparse.Namespace) -> int: + store = _store_path(args) + todos = load_todos(store) + todo = add_todo(todos, args.text) + save_todos(store, todos) + print(f"added #{todo['id']}: {todo['text']}") + return 0 + + +def cmd_list(args: argparse.Namespace) -> int: + store = _store_path(args) + print(render(load_todos(store))) + return 0 + + +def build_parser() -> argparse.ArgumentParser: + parser = argparse.ArgumentParser(prog="todo", description="A tiny todo list.") + parser.add_argument("--file", help="path to the JSON store (default: ./todos.json)") + sub = parser.add_subparsers(dest="command", required=True) + + p_add = sub.add_parser("add", help="add a todo") + p_add.add_argument("text", help="the task text") + p_add.set_defaults(func=cmd_add) + + p_list = sub.add_parser("list", help="list todos") + p_list.set_defaults(func=cmd_list) + + # BACKLOG #F1: `done ` (mark complete) — the first feature built in Tutorial 2. + # BACKLOG #F2: `rm ` (delete a todo). + return parser + + +def main(argv: list[str] | None = None) -> int: + args = build_parser().parse_args(argv) + return args.func(args) + + +if __name__ == "__main__": + sys.exit(main()) From 36f3a2641e63c2339e3125a8f72b5789a7e1e877 Mon Sep 17 00:00:00 2001 From: "R. Mark Sharp" Date: Sat, 20 Jun 2026 17:13:38 -0500 Subject: [PATCH 2/7] docs(tutorials): add series index + shared tutorial template (P1) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README.md: series index — "Why bother?" hook (links the canonical case, does not restate it), how-the-series-works rules, Track A/B explainer, curriculum table (core trio T1/T2/T5 first cut; T3/T4/T6/T7/T8 roadmap), scaffolding-only status note. - TUTORIAL_TEMPLATE.md: one shared shape per plan §8 — front-matter (Objective/Prerequisites/Time/What you'll produce/Track), "You do X → Expected result" steps with checkpoints, Common-mistakes callouts citing FMs by number (cite-don't-restate), "Why this matters" hook, Next pointer. All cross-file links and anchor slugs verified to resolve (Learning #7). Part of tutorial-series plan §9 P1. No tutorial content yet. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/tutorials/README.md | 68 ++++++++++++++++++++++++ docs/tutorials/TUTORIAL_TEMPLATE.md | 82 +++++++++++++++++++++++++++++ 2 files changed, 150 insertions(+) create mode 100644 docs/tutorials/README.md create mode 100644 docs/tutorials/TUTORIAL_TEMPLATE.md diff --git a/docs/tutorials/README.md b/docs/tutorials/README.md new file mode 100644 index 00000000..72b29c5e --- /dev/null +++ b/docs/tutorials/README.md @@ -0,0 +1,68 @@ +# Tutorials + +A hands-on, progressive learning track for the Iterative Session Methodology. The other +docs *define* the framework — this one makes you *do* it, one thing at a time, against a real +project, with a checkpoint after each step. + +> **Status:** Scaffolding only. This index, the [tutorial template](TUTORIAL_TEMPLATE.md), and +> the [sample project](sample-project/) are in place; the tutorial content (T1, T2, T5) lands in +> later sessions. The curriculum below shows what's coming. + +## Why bother? + +You can read the [9 principles, 6 phases, and 12 gates](../../ITERATIVE_METHODOLOGY.md) and still +not know how to *run* a session. These tutorials close that gap: you install the framework, run +one real session end to end, and see where the guardrails catch you. The payoff — fewer wrecked +sessions, and session N+1 reliably better than session N — is documented, not promised: + +- [The Problem](../../README.md#the-problem) and [Evidence](../../README.md#evidence) — why the methodology exists and what it changed. +- [When to Use This Methodology](../../ITERATIVE_METHODOLOGY.md#when-to-use-this-methodology) — and when not to. +- [The Self-Improvement Loop](../../ITERATIVE_METHODOLOGY.md#the-self-improvement-loop) — the compounding payoff these tutorials let you feel firsthand. + +## How the series works + +- **One objective per tutorial** — mirrors the methodology's "1 deliverable per session." Each + tutorial does exactly one thing. +- **Progressive** — T1 → T2 → T5 build on each other; every tutorial names its predecessor. +- **You produce a real artifact** — an installed framework, a saved session doc, a feature you + shipped, a near-miss you caught. Not read-along. +- **Cite, don't restate** — tutorials link into [`BOOTSTRAP.md`](../../starter-kit/BOOTSTRAP.md), + [`SESSION_RUNNER.md`](../../starter-kit/SESSION_RUNNER.md), and + [`ITERATIVE_METHODOLOGY.md`](../../ITERATIVE_METHODOLOGY.md) at the right beat. One source of + truth; the tutorials never fork the principles, phases, or failure-mode list. +- **Dogfooded** — each tutorial is itself authored as a methodology session. + +## Two ways to practice — pick one per pass + +Choose a single track for a given run (do one, then the other if you like — not both at once): + +- **Track A — your own repo.** Apply each step to a project you actually care about. The sample + run is your reference for "what a good run looks like." +- **Track B — the bundled sample.** Use the [sample project](sample-project/) (a tiny todo CLI + with a real test suite and a [backlog](sample-project/BACKLOG.md)) and follow the steps + step-for-step in a throwaway sandbox. + +One running example threads the core trio: T1 installs the framework onto the sample project, T2 +runs the first session (building one todo-CLI feature), and T5 uses that same session's +near-misses as its cautionary cases. + +## Curriculum + +The **core trio (T1 · T2 · T5)** is the first cut; the rest is a roadmap. + +| # | Tutorial | You'll be able to… | In first cut? | +|---|----------|--------------------|:-------------:| +| T1 | Setup & First Bootstrap | Install the framework into a project: root files, `CLAUDE.md` protocol block, task tracking, dashboard | ✅ planned | +| T2 | Your First Session, End-to-End | Run one full 6-phase pass to one deliverable — with Phase 0 Orient and the Present gate front and center | ✅ planned | +| T5 | Cautionary Use | Read the gates, the 26 failure modes, "1 and done", the vertical-slice gates, and the Plan-Mode exit trap — and know when the methodology is too heavy | ✅ planned | +| T3 | The Compounding Loop | Run the handoff + scoring loop and watch session N+1 improve | roadmap | +| T4 | Choosing & Adapting a Workstream | Pick the right workstream; spin up a custom one | roadmap | +| T6 | Multi-Session Campaigns | Carry one deliverable across many sessions | roadmap | +| T7 | Portfolio & Dashboard Ops | Run across many projects; read the health dashboard | roadmap | +| T8 | Keeping Adopters Current | Use `bin/sync` / `bin/status` to stay in step with the canonical repo | roadmap | + +## Writing a tutorial + +Start from [`TUTORIAL_TEMPLATE.md`](TUTORIAL_TEMPLATE.md) — it encodes the shared anatomy +(front-matter, "You do X → Expected result" steps with checkpoints, FM-by-number callouts, the +"Why this matters" hook, and the successor pointer). diff --git a/docs/tutorials/TUTORIAL_TEMPLATE.md b/docs/tutorials/TUTORIAL_TEMPLATE.md new file mode 100644 index 00000000..a65ca21d --- /dev/null +++ b/docs/tutorials/TUTORIAL_TEMPLATE.md @@ -0,0 +1,82 @@ + + +# Tutorial [N]: [Title] + +> **Objective:** [The single thing the learner will be able to do by the end. One sentence.] +> **Prerequisites:** [Tutorial N-1] ([link]); [any tools/accounts]. New here? Start at the [series index](README.md). +> **Time:** [~N minutes] +> **What you'll produce:** [The concrete artifact the learner walks away with — an installed framework, a saved session doc, a merged feature, a caught near-miss.] +> **Track:** Pick one and stick with it for this pass — +> **A** (your own repo): apply each step to a project you care about; the sample run is your reference. +> **B** ([sample project](sample-project/)): clone/use the bundled todo CLI and follow along step-for-step. + +## Why this matters + +[2–3 sentences of payoff, then LINK the canonical case — do not restate it. Pull from: +[The Problem](../../README.md#the-problem) · [Evidence](../../README.md#evidence) · +[When to Use This Methodology](../../ITERATIVE_METHODOLOGY.md#when-to-use-this-methodology) · +[The Self-Improvement Loop](../../ITERATIVE_METHODOLOGY.md#the-self-improvement-loop).] + +## Before you start + +[Anything that must be true first: prior tutorial completed, tools installed, repo cloned. +Give the one command or check that confirms readiness.] + +**Checkpoint:** [What the learner should see that proves they're ready to begin.] + +## Steps + +Each step is one action and its expected result. Don't skip ahead — later steps assume the +checkpoints passed. + +### 1. [You do X] + +[Exact instruction — the command to run or the edit to make.] + +**Expected result:** [What happens.] +**Checkpoint:** [What the learner should now see / have. Be concrete enough to self-verify.] + +### 2. [You do Y] + +[…] + +**Expected result:** […] +**Checkpoint:** […] + + + +## Common mistakes + +Cite the failure mode by number; link the list, don't paste it. +(Full list: [Known Failure Modes](../../starter-kit/SESSION_RUNNER.md#known-failure-modes).) + +- **[Mistake the learner is likely to make here]** — [one line]. This is **FM #[n]**; the + countermeasure is [the gate/step that prevents it]. +- **[Another]** — [one line]. See **FM #[n]**. + +## You produced + +[Restate the artifact from the front-matter, now in the past tense, so the learner sees they +made something real. If it's part of the running example threaded through the series, say how +the next tutorial builds on it.] + +## Next + +→ **[Tutorial N+1: Title](T[N+1]_[slug].md)** — [one line on what it adds]. From 26229e66cdd8d00e92b8e82292fb41625c019760 Mon Sep 17 00:00:00 2001 From: "R. Mark Sharp" Date: Sat, 20 Jun 2026 17:14:54 -0500 Subject: [PATCH 3/7] docs: wire tutorial discoverability (README + BOOTSTRAP) (P1) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README.md: new ## Tutorials section (relative link to docs/tutorials/) + docs/ branch added to the Repository Structure tree. - starter-kit/BOOTSTRAP.md: one-line "learn by doing first" pointer near the intro. Absolute github.com URL by design — BOOTSTRAP is copied into adopter trees at setup, where a relative link to the non-distributed tutorials would dangle. Canonical-repo discovery only this session; the synced-file (SESSION_RUNNER / SAFEGUARDS) adopter pointer is deferred (BOOTSTRAP is not in the sync set, and the only synced host is byte-sensitive — revisit once B1 reshapes the corpus). Part of tutorial-series plan §9 P1. Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 7 +++++++ starter-kit/BOOTSTRAP.md | 2 ++ 2 files changed, 9 insertions(+) diff --git a/README.md b/README.md index 37463219..c4e436a9 100644 --- a/README.md +++ b/README.md @@ -141,6 +141,10 @@ Expand any project card to see health breakdown by dimension, risk factors, git ![Expanded project detail showing health breakdown, code metrics, and methodology compliance](docs/images/dashboard-detail.png) +## Tutorials + +New to the methodology? The **[tutorials](docs/tutorials/)** are a hands-on, progressive learning track — install the framework, run a real session end to end, and learn where the guardrails catch you. Each lesson has you *do* one thing against a real project (your own repo, or the bundled [sample project](docs/tutorials/sample-project/)), with a checkpoint at every step. The core trio (Setup → First Session → Cautionary Use) is in progress; see the **[series index](docs/tutorials/)** for the full curriculum. + ## Repository Structure ``` @@ -169,6 +173,9 @@ Expand any project card to see health breakdown by dimension, risk factors, git │ ├── ROADMAP.md ← Feature inventory & future plans template │ └── methodology_dashboard.py ← Health scanner (also in tools/) │ +├── docs/ ← Tutorials and supporting docs +│ └── tutorials/ ← Hands-on learning track + sample todo-CLI project +│ ├── bin/ ← Sync tools (v2.2+) │ ├── sync ← Copy starter-kit files into a project (dual-mode, dual-source) │ └── status ← Report drift of synced files across projects diff --git a/starter-kit/BOOTSTRAP.md b/starter-kit/BOOTSTRAP.md index 7ab026e2..dcc2ac7c 100644 --- a/starter-kit/BOOTSTRAP.md +++ b/starter-kit/BOOTSTRAP.md @@ -2,6 +2,8 @@ Set up the Iterative Session Methodology for a new project in 10 minutes. +> **Prefer to learn by doing first?** Walk the [tutorials](https://github.com/KJ5HST/methodology/tree/main/docs/tutorials) — a hands-on track that installs the framework and runs a real session step by step (against your own repo or a bundled sample project). This guide is the reference you'll come back to when setting up your own project. + --- ## What You'll Have When Done From 18ce1f6fbe23676e7eb54b7ad0aa11513337e5f7 Mon Sep 17 00:00:00 2001 From: "R. Mark Sharp" Date: Sat, 20 Jun 2026 17:34:32 -0500 Subject: [PATCH 4/7] docs(tutorials): add T1 Setup & First Bootstrap (P2) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Write Tutorial 1 against TUTORIAL_TEMPLATE.md: a hands-on walkthrough that installs the framework into a project (Track A own repo / Track B bundled sample), ending with a bootstrapped project ready for its first session. - Cites BOOTSTRAP steps, README Quick Start, bin/sync, the SAFEGUARDS build equivalent, and SESSION_RUNNER failure modes by number — never restates them. - Common-mistakes section ties the setup-then-"go" trap to FM #1 and the synced-file-edit drift to FM #17. - Wires T1 into the series index (status banner + curriculum row). - Forward pointer to T2 is plain text, not a live link, until T2 lands in P3 — matching the index's treatment of unwritten tutorials (no 404 today). Verify: every cited anchor grep-checked to resolve; ./bin/tests.sh 28/0; sample-project pytest 7/7; bin/sync --dry-run emits zero docs/tutorials files (non-distribution invariant holds). Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/tutorials/README.md | 8 +-- docs/tutorials/T1_setup.md | 133 +++++++++++++++++++++++++++++++++++++ 2 files changed, 137 insertions(+), 4 deletions(-) create mode 100644 docs/tutorials/T1_setup.md diff --git a/docs/tutorials/README.md b/docs/tutorials/README.md index 72b29c5e..0665e40a 100644 --- a/docs/tutorials/README.md +++ b/docs/tutorials/README.md @@ -4,9 +4,9 @@ A hands-on, progressive learning track for the Iterative Session Methodology. Th docs *define* the framework — this one makes you *do* it, one thing at a time, against a real project, with a checkpoint after each step. -> **Status:** Scaffolding only. This index, the [tutorial template](TUTORIAL_TEMPLATE.md), and -> the [sample project](sample-project/) are in place; the tutorial content (T1, T2, T5) lands in -> later sessions. The curriculum below shows what's coming. +> **Status:** [Tutorial 1: Setup & First Bootstrap](T1_setup.md) is published. The +> [tutorial template](TUTORIAL_TEMPLATE.md) and [sample project](sample-project/) are in place; +> T2 and T5 land in later sessions. The curriculum below shows what's done and what's coming. ## Why bother? @@ -52,7 +52,7 @@ The **core trio (T1 · T2 · T5)** is the first cut; the rest is a roadmap. | # | Tutorial | You'll be able to… | In first cut? | |---|----------|--------------------|:-------------:| -| T1 | Setup & First Bootstrap | Install the framework into a project: root files, `CLAUDE.md` protocol block, task tracking, dashboard | ✅ planned | +| [T1](T1_setup.md) | Setup & First Bootstrap | Install the framework into a project: root files, `CLAUDE.md` protocol block, task tracking, dashboard | ✅ **published** | | T2 | Your First Session, End-to-End | Run one full 6-phase pass to one deliverable — with Phase 0 Orient and the Present gate front and center | ✅ planned | | T5 | Cautionary Use | Read the gates, the 26 failure modes, "1 and done", the vertical-slice gates, and the Plan-Mode exit trap — and know when the methodology is too heavy | ✅ planned | | T3 | The Compounding Loop | Run the handoff + scoring loop and watch session N+1 improve | roadmap | diff --git a/docs/tutorials/T1_setup.md b/docs/tutorials/T1_setup.md new file mode 100644 index 00000000..ae031ba1 --- /dev/null +++ b/docs/tutorials/T1_setup.md @@ -0,0 +1,133 @@ +# Tutorial 1: Setup & First Bootstrap + +> **Objective:** Install the Iterative Session Methodology into a project so that every future session has an operating procedure to follow. +> **Prerequisites:** None — this is where the series starts. You need a terminal, `git`, and Python 3. New here? Read the [series index](README.md) first. +> **Time:** ~15 minutes +> **What you'll produce:** A bootstrapped project — `SESSION_RUNNER.md`, `SAFEGUARDS.md`, `SESSION_NOTES.md`, the three task-tracking files, a `CLAUDE.md` with the SESSION PROTOCOL block, and a generated dashboard — ready for its first real session in Tutorial 2. +> **Track:** Pick one and stick with it for this pass — +> **A** (your own repo): apply each step to a project you care about; the sample run is your reference. +> **B** ([sample project](sample-project/)): use the bundled todo CLI and follow along step-for-step in a throwaway sandbox. + +## Why this matters + +Setup is the cheapest place to make the methodology pay off and the easiest to skip. The entire self-correcting loop — orient, one deliverable, close out, score the handoff — only runs if the operating procedure is installed where the agent reads it. Fifteen minutes here is what makes session N+1 reliably better than session N. The case for why that compounding is worth it is documented, not promised: + +- [The Problem](../../README.md#the-problem) and [Evidence](../../README.md#evidence) — why the methodology exists and what it changed. +- [When to Use This Methodology](../../ITERATIVE_METHODOLOGY.md#when-to-use-this-methodology) — and when not to. +- [The Self-Improvement Loop](../../ITERATIVE_METHODOLOGY.md#the-self-improvement-loop) — the compounding payoff Tutorial 2 lets you feel firsthand. + +## Before you start + +Confirm your toolchain, then choose where you'll install the framework. + +```sh +git --version # any recent git +python3 --version # Python 3.8+ +``` + +- **Track A — your own repo.** Pick a project you can practice in. So setup is trivial to undo, work on a scratch branch: + ```sh + cd your-project + git switch -c methodology-practice + ``` +- **Track B — the bundled sample.** Copy the sample *out* of the methodology repo into a throwaway location, so your practice edits never touch the methodology checkout, and make it a standalone repo: + ```sh + cp -r docs/tutorials/sample-project ~/todo-practice + cd ~/todo-practice + git init -q && git add -A && git commit -qm "start: sample todo CLI" + ``` + +**Checkpoint:** You're inside a git repo you're willing to throw away or revert. Track B learners: run `python -m pytest` — all tests pass. That green suite is this project's [build equivalent](../../starter-kit/SAFEGUARDS.md#verify-the-build-equivalent); you'll record it in Step 4. + +## Steps + +Each step is one action and its expected result. Don't skip ahead — the final step (start a fresh session) only works if the earlier ones put the protocol on disk first. + +### 1. Copy the methodology files into your project + +You have two ways to do this; both are first-class. The scripted path is fastest if you have a local `methodology/` checkout (Track B learners already do — it's where the sample came from). + +```sh +# Scripted (committed mode is the default): +../methodology/bin/sync . + +# …or, with no sibling checkout, pull from GitHub (needs the gh CLI): +../methodology/bin/sync . --source=github +``` + +For the manual path, or the difference between committed and ignored modes, see [`BOOTSTRAP.md` §Setup with `bin/sync`](../../starter-kit/BOOTSTRAP.md#setup-with-binsync-recommended) and [§Setup by manual copy](../../starter-kit/BOOTSTRAP.md#setup-by-manual-copy-always-valid). + +**Expected result:** `bin/sync` copies `SESSION_RUNNER.md`, `SAFEGUARDS.md`, and `methodology_dashboard.py` into the project. +**Checkpoint:** `ls SESSION_RUNNER.md SAFEGUARDS.md methodology_dashboard.py` lists all three. + +### 2. Tell your agent to use it — the SESSION PROTOCOL block + +The agent reads `CLAUDE.md` at the start of every session, so the methodology is "installed" the moment this block is the first thing in that file. Add it to your project's `CLAUDE.md` (create the file if there isn't one — Track B starts without one): + +```markdown +## SESSION PROTOCOL — FOLLOW BEFORE DOING ANYTHING + +Read and follow `SESSION_RUNNER.md` step by step. It is your operating procedure +for every session. It tells you what to read, when to stop, and how to close out. +``` + +The full block (with the three rules you'll be tempted to violate) and the `CLAUDE_TEMPLATE.md` starting point are in [`BOOTSTRAP.md` §Step 4](../../starter-kit/BOOTSTRAP.md#step-4-create-or-update-your-claudemd). If you're starting a `CLAUDE.md` from scratch, Claude Code's `/init` can scaffold one from the project structure first — then paste the block in. + +**Expected result:** `CLAUDE.md` exists at the project root and opens with the SESSION PROTOCOL heading. +**Checkpoint:** The first section of `CLAUDE.md` is `## SESSION PROTOCOL — FOLLOW BEFORE DOING ANYTHING`. + +### 3. Set up task tracking — the three-file split + +Open work, completed history, and future plans live in three separate files so the one the agent reads at session start (`BACKLOG.md`) stays scannable. See [`BOOTSTRAP.md` §Step 3](../../starter-kit/BOOTSTRAP.md#step-3-create-your-task-tracking-files). + +- **Track B:** the sample already ships a [`BACKLOG.md`](sample-project/BACKLOG.md) — that *is* your project backlog. Its first item, `F1: todo done `, is exactly the feature you'll build end-to-end in Tutorial 2. Copy the `CHANGELOG.md` and `ROADMAP.md` templates from `starter-kit/` to the project root. +- **Track A:** create a `BACKLOG.md` with your open items only (no completed work), and copy the `CHANGELOG.md` / `ROADMAP.md` templates from `starter-kit/`. + +**Expected result:** three files at the root — `BACKLOG.md` (open items only), `CHANGELOG.md`, `ROADMAP.md`. +**Checkpoint:** `BACKLOG.md` lists only actionable work and reads in under a minute; `CHANGELOG.md` and `ROADMAP.md` both exist. + +### 4. Record your build equivalent + +Every project has one command that confirms the deliverable isn't broken. Identify it now and record it in `SAFEGUARDS.md`'s [Verify the Build Equivalent](../../starter-kit/SAFEGUARDS.md#verify-the-build-equivalent) section, per [`BOOTSTRAP.md` §Step 6](../../starter-kit/BOOTSTRAP.md#step-6-identify-the-build-equivalent). For the sample project (Track B) it's the test suite: + +```sh +python -m pytest # the documented runner +python -m unittest # stdlib fallback, zero dependencies +``` + +**Expected result:** your project's verification command is written down where every session will look for it. +**Checkpoint:** You can name your build equivalent without thinking. Track B: `python -m pytest` reports all green. + +### 5. Generate the dashboard + +```sh +python3 methodology_dashboard.py +``` + +This writes `dashboard.html` and opens it; the page auto-refreshes every 60 seconds. Add `dashboard.html` to your `.gitignore` — it's a generated artifact. See [`BOOTSTRAP.md` §Step 9](../../starter-kit/BOOTSTRAP.md#step-9-set-up-the-methodology-dashboard-recommended). + +**Expected result:** a health report you can open in a browser. +**Checkpoint:** `dashboard.html` exists and your project's methodology-compliance score is no longer zero. + +### 6. Stop here — then start a *fresh* session + +This is the one step everyone gets wrong. The agent read `CLAUDE.md` when this session began — *before* you installed the protocol — so the procedure you just set up is not loaded in the session you set it up in. Do **not** give a real task now. + +**Expected result:** setup is complete and committed; no feature work has begun. +**Checkpoint:** You have started a brand-new session (or are about to). The agent's first act in that session is to orient — read `SAFEGUARDS.md` and `SESSION_NOTES.md`, run the dashboard, check `git status`, report, and wait for you. That's [`BOOTSTRAP.md` §First Session Checklist](../../starter-kit/BOOTSTRAP.md#first-session-checklist), and it's exactly what Tutorial 2 walks through. + +## Common mistakes + +Cite the failure mode by number; link the list, don't paste it. +(Full list: [Known Failure Modes](../../starter-kit/SESSION_RUNNER.md#known-failure-modes).) + +- **Setting up and saying "go" in the same session.** The just-installed protocol isn't loaded yet, so the agent works unguided — Phase 0 never runs. This is **FM #1 (eager to start)** in a setup costume; the countermeasure is Step 6 above — start a fresh session before your first real task. +- **Customizing by editing `SESSION_RUNNER.md` (or `SAFEGUARDS.md`).** Those edits become drift and block future `bin/sync` updates. Put project-specific mappings and steps in your `CLAUDE.md` "Project-Specific Methodology Adaptations" section instead — see [`BOOTSTRAP.md` §Step 5](../../starter-kit/BOOTSTRAP.md#step-5-customizations-go-in-claudemd-not-in-synced-files) and [§Step 7](../../starter-kit/BOOTSTRAP.md#step-7-customize-the-task-mapping-table). Keeping synced files byte-identical to canonical is the same protocol-integrity instinct that **FM #17 (protocol erosion)** guards: don't subtract from, or fork, the shared procedure. + +## You produced + +A bootstrapped project: the operating procedure (`SESSION_RUNNER.md`), the safety rails (`SAFEGUARDS.md`), session continuity (`SESSION_NOTES.md`), the three task-tracking files, a `CLAUDE.md` that points every session at the procedure, and a health dashboard. Nothing has run a session yet — that's the point. In Tutorial 2 you start a fresh session against this very project and take one backlog item (Track B: `F1: todo done `) through all six phases to a single shipped deliverable. + +## Next + +→ **Tutorial 2: Your First Session, End-to-End** *(coming in the next session)* — run one full 6-phase pass to one deliverable, with Phase 0 Orient and the Present gate front and center. This pointer becomes a live link to `T2_first_session.md` when that tutorial lands. From 061282861cceac543afcd40509f927ef5a803d9c Mon Sep 17 00:00:00 2001 From: "R. Mark Sharp" Date: Sun, 21 Jun 2026 01:31:00 -0500 Subject: [PATCH 5/7] docs(tutorials): add T2 First Session + worked transcript (P3) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Write Tutorial 2 (Your First Session, End-to-End) and the worked transcript it is built around — a real, recorded six-phase methodology session building backlog item F1 (`todo done `) against the sample project. - T2_worked_transcript.md: faithful Orient -> Receive/Claim -> Execute (Research -> Create -> Present STOP -> Implement) -> Close-Out (3A-3G) run with REAL outputs captured from an actual sandbox execution: baseline 7 tests, red 5, green 12 (7+5), CLI smoke (`done #1` -> `[x]`, unknown id -> exit 1), and the +32-line diff. Present-gate STOP explicit; 3A skipped (Session 1); staleness/re-record note. The committed sample stays incomplete — F1 is the learner's job, never implemented under docs/tutorials/sample-project/. - T2_first_session.md: written against TUTORIAL_TEMPLATE.md; one objective, Phase 0 Orient and the Present gate front and center; checkpoints match the transcript; cites SESSION_RUNNER / ITERATIVE_METHODOLOGY#the-6-phases / HOW_TO_USE#running-your-first-session and failure modes by number — never restates them. - Wire-up: README series index (status banner + T2 row -> published, plus a worked-transcript link); T1 forward pointer is now a live link to T2. Adversarially verified (multi-agent review + refutation): fixed a missing close-out step 3C and a non-canonical 3E-before-3D order in the transcript, and a Phase-1B cross-reference anchor that pointed at the parent heading. Verify: ./bin/tests.sh 28/0; sample-project pytest 7/7 with F1 still absent; bin/sync --dry-run emits zero docs/tutorials files (non-distribution holds); 69 intra-repo links + anchors resolve; close-out order canonical 3A-3G. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/tutorials/README.md | 8 +- docs/tutorials/T1_setup.md | 2 +- docs/tutorials/T2_first_session.md | 116 +++++++++++ docs/tutorials/T2_worked_transcript.md | 256 +++++++++++++++++++++++++ 4 files changed, 378 insertions(+), 4 deletions(-) create mode 100644 docs/tutorials/T2_first_session.md create mode 100644 docs/tutorials/T2_worked_transcript.md diff --git a/docs/tutorials/README.md b/docs/tutorials/README.md index 0665e40a..20831316 100644 --- a/docs/tutorials/README.md +++ b/docs/tutorials/README.md @@ -4,9 +4,11 @@ A hands-on, progressive learning track for the Iterative Session Methodology. Th docs *define* the framework — this one makes you *do* it, one thing at a time, against a real project, with a checkpoint after each step. -> **Status:** [Tutorial 1: Setup & First Bootstrap](T1_setup.md) is published. The +> **Status:** [Tutorial 1: Setup & First Bootstrap](T1_setup.md) and +> [Tutorial 2: Your First Session, End-to-End](T2_first_session.md) are published — T2 ships with a +> [worked transcript](T2_worked_transcript.md) of a real session against the sample project. The > [tutorial template](TUTORIAL_TEMPLATE.md) and [sample project](sample-project/) are in place; -> T2 and T5 land in later sessions. The curriculum below shows what's done and what's coming. +> T5 lands in a later session. The curriculum below shows what's done and what's coming. ## Why bother? @@ -53,7 +55,7 @@ The **core trio (T1 · T2 · T5)** is the first cut; the rest is a roadmap. | # | Tutorial | You'll be able to… | In first cut? | |---|----------|--------------------|:-------------:| | [T1](T1_setup.md) | Setup & First Bootstrap | Install the framework into a project: root files, `CLAUDE.md` protocol block, task tracking, dashboard | ✅ **published** | -| T2 | Your First Session, End-to-End | Run one full 6-phase pass to one deliverable — with Phase 0 Orient and the Present gate front and center | ✅ planned | +| [T2](T2_first_session.md) | Your First Session, End-to-End | Run one full 6-phase pass to one deliverable — with Phase 0 Orient and the Present gate front and center | ✅ **published** | | T5 | Cautionary Use | Read the gates, the 26 failure modes, "1 and done", the vertical-slice gates, and the Plan-Mode exit trap — and know when the methodology is too heavy | ✅ planned | | T3 | The Compounding Loop | Run the handoff + scoring loop and watch session N+1 improve | roadmap | | T4 | Choosing & Adapting a Workstream | Pick the right workstream; spin up a custom one | roadmap | diff --git a/docs/tutorials/T1_setup.md b/docs/tutorials/T1_setup.md index ae031ba1..efdb8342 100644 --- a/docs/tutorials/T1_setup.md +++ b/docs/tutorials/T1_setup.md @@ -130,4 +130,4 @@ A bootstrapped project: the operating procedure (`SESSION_RUNNER.md`), the safet ## Next -→ **Tutorial 2: Your First Session, End-to-End** *(coming in the next session)* — run one full 6-phase pass to one deliverable, with Phase 0 Orient and the Present gate front and center. This pointer becomes a live link to `T2_first_session.md` when that tutorial lands. +→ **[Tutorial 2: Your First Session, End-to-End](T2_first_session.md)** — run one full 6-phase pass to one deliverable, with Phase 0 Orient and the Present gate front and center. diff --git a/docs/tutorials/T2_first_session.md b/docs/tutorials/T2_first_session.md new file mode 100644 index 00000000..c2e333a6 --- /dev/null +++ b/docs/tutorials/T2_first_session.md @@ -0,0 +1,116 @@ +# Tutorial 2: Your First Session, End-to-End + +> **Objective:** Run one complete methodology session — all six phases, one deliverable — so you have felt the loop the framework is built around, especially Phase 0 Orient and the Present gate. +> **Prerequisites:** [Tutorial 1: Setup & First Bootstrap](T1_setup.md) (the framework must be installed). You need a terminal, `git`, and Python 3. New here? Start at the [series index](README.md). +> **Time:** ~30 minutes +> **What you'll produce:** One shipped, tested feature (Track B: `todo done `) reached through all six phases, plus a `SESSION_NOTES.md` handoff a *next* session could act on without re-discovery. +> **Track:** Pick one and stick with it for this pass — +> **A** (your own repo): take one real backlog item through the six phases; the [worked transcript](T2_worked_transcript.md) is your reference for "what a good run looks like." +> **B** ([sample project](sample-project/)): build backlog item **F1 — `todo done `** by replaying the [worked transcript](T2_worked_transcript.md) step-for-step in your sandbox. + +## Why this matters + +Tutorial 1 installed the operating procedure; this is where you *run* it and feel why each phase earns its place. Two phases do the heavy lifting and are the ones every newcomer is tempted to skip: **Phase 0 (Orient)** — read before you touch anything — and the **Present gate** — show the plan and stop until it's approved. By the end you'll have taken one real deliverable from a clean tree to a verified commit without either skip. The payoff is documented, not promised: + +- [The Self-Improvement Loop](../../ITERATIVE_METHODOLOGY.md#the-self-improvement-loop) — the compounding you start feeling the moment this session writes a handoff the next one reads. +- [When to Use This Methodology](../../ITERATIVE_METHODOLOGY.md#when-to-use-this-methodology) — and when a session like this is overkill. +- [Evidence](../../README.md#evidence) — what running sessions this way actually changed. + +The six phases themselves are defined in the [flight manual](../../ITERATIVE_METHODOLOGY.md#the-6-phases) and operated by the [cockpit checklist](../../starter-kit/SESSION_RUNNER.md); this tutorial doesn't restate them — it makes you run one. For another angle on the same first run, see [`HOW_TO_USE.md` §Running Your First Session](../../HOW_TO_USE.md#running-your-first-session). + +## Before you start + +You need the bootstrapped project from Tutorial 1 — the one with `SESSION_RUNNER.md`, `SAFEGUARDS.md`, `SESSION_NOTES.md`, the task-tracking files, and a `CLAUDE.md` whose first section is the SESSION PROTOCOL block. Confirm the build equivalent is green before you change anything: + +```sh +# Track B, from inside your sandbox copy of the sample project: +python -m pytest # expect: 7 passed +``` + +Read the [worked transcript](T2_worked_transcript.md) once now, start to finish. It's short, and it's the artifact every checkpoint below maps to — Track B learners will reproduce its tool output almost line for line. + +**Checkpoint:** Your tree is clean (`git status`), tests are green, and `CLAUDE.md` opens with the SESSION PROTOCOL heading. You're about to start a *fresh* session — not the one that did setup. + +## Steps + +Each step is one phase of the session, in order. The whole point is that you can't reorder them: orientation gates the task, the plan gates the code, the close-out gates the next session. Don't skip ahead. + +### 1. Start a fresh session and let it orient — do NOT give a task yet + +Open a brand-new session against the bootstrapped project (this is the "fresh session" Tutorial 1 Step 6 set you up for). The agent has just read `CLAUDE.md`, so its first act is **Phase 0: Orient** — read `SAFEGUARDS.md`, read `SESSION_NOTES.md`, check the backlog, run `git status` and the dashboard, check for ghost sessions, **report, and wait.** + +Your only job here is to let it finish orienting without handing it work. + +**Expected result:** The agent reports current state and stops — clean tree, "Session 1, no prior session," backlog top item is F1, baseline `7 passed` — then asks for a task. +**Checkpoint:** You received an orientation report and a request for direction. Nothing has changed on disk. (If the agent started editing files, it skipped Phase 0 — [FM #1](../../starter-kit/SESSION_RUNNER.md#known-failure-modes).) + +### 2. Give exactly one task — and watch it claim the session + +Now hand over **one** deliverable: + +- **Track B:** *"Implement F1 — `todo done `."* +- **Track A:** name one small, vertical, testable item from your own backlog. One. Not two "while we're here." + +The agent restates the deliverable, then — before any code — writes a **claim stub** to `SESSION_NOTES.md` (Phase 1B). That stub is what guarantees even a crashed session leaves a trace. + +**Expected result:** The agent echoes back one deliverable and one workstream, then writes the IN-PROGRESS stub. +**Checkpoint:** `SESSION_NOTES.md` now contains a "What Session 1 Did … Status: Session claimed" stub. (See the transcript's [Phase 1B](T2_worked_transcript.md#1b--claim-the-session).) + +### 3. Let it research and produce a plan — before any code + +This is **Phase 2: Execute**, and its first move is *not* typing code. The agent reads the actual implementation it's about to change, states the expected vs. current behavior and the acceptance criteria, and challenges scope. For the sample, reading `add_todo` surfaces the empty-text bug **B1** — and the correct move is to *defer* it, not fix it. The output of this step is an **implementation plan** (what changes, what's explicitly out of scope, the test plan). + +**Expected result:** A written plan: `mark_done` + `cmd_done` + a `done` subparser, five tests written first, and B1 named as out of scope. +**Checkpoint:** You can see a plan with an explicit **"What I'm NOT changing"** boundary. B1 is listed there, not in the change set. (Fixing B1 here would be scope creep — [FM #2](../../starter-kit/SESSION_RUNNER.md#known-failure-modes)/[#8](../../starter-kit/SESSION_RUNNER.md#known-failure-modes).) + +### 4. The Present gate — approve before a line of code + +The agent presents the plan and **stops**. This feels unnatural — the plan is small and obvious — and stopping anyway is exactly the discipline. Read the plan. If it's right, approve it; if not, send it back to revise. **No implementation happens until you say go.** + +**Expected result:** The agent waits for your explicit approval and does not edit code until it has it. +**Checkpoint:** You gave an explicit "approved" (or requested changes) *before* any file changed. This is the highest-ROI gate in the methodology — a flawed plan caught here costs zero implementation effort. (Coding through this gate is the [Present-gate skip](../../ITERATIVE_METHODOLOGY.md#the-6-phases).) + +### 5. Implement test-first — red, then green + +With approval, the agent implements in the **test-first** order: write the failing tests, run them to confirm they fail *for the right reason* (red), then make the change and re-run the **full** suite (green). + +```sh +# Track B — you'll see, in order: +python -m pytest test_done.py -q # red: 5 failed (done is an invalid choice) +# …agent applies the change to todo.py… +python -m pytest -q # green: 12 passed (7 original + 5 new) +``` + +**Expected result:** Five new tests fail before the change and pass after; the original seven never break. +**Checkpoint:** Red showed `5 failed`; green shows `12 passed`. A regression in the original 7 would mean stop and re-research — not patch forward. (A test that passes *before* the feature exists is testing nothing — [test-last](../../workstreams/DEVELOPMENT_WORKSTREAM.md#common-anti-patterns-development) is anti-pattern #3.) + +### 6. Close out — hand off, runtime-verify, commit, and STOP + +**Phase 3** is automatic; the agent does it without being asked, in order: record any project learning (3C), write the handoff (3D), then — because this deliverable changes runtime behavior — actually run the app to confirm the feature is live (3E; "tests pass" is not enough for a runtime change), and finally commit one atomic change (3F) and stop. + +```sh +# Track B runtime smoke test — the feature is active, not just compiled: +python3 todo.py --file demo.json add "write the report" +python3 todo.py --file demo.json done 1 # -> done #1: write the report +python3 todo.py --file demo.json list # -> 1 [x] write the report +``` + +**Expected result:** A full handoff written to `SESSION_NOTES.md` (what was done + commit, what's next, key files with line numbers, gotchas, a self-assessment score), a runtime smoke test, one commit, and a stop. +**Checkpoint:** `SESSION_NOTES.md` holds a handoff that names the next item (F2) and the key files; `git log` shows one feature commit; the agent did **not** start F2 or fix B1. That stop is "1 and done" — [FM #2](../../starter-kit/SESSION_RUNNER.md#known-failure-modes). + +## Common mistakes + +Cite the failure mode by number; link the list, don't paste it. +(Full list: [Known Failure Modes](../../starter-kit/SESSION_RUNNER.md#known-failure-modes).) + +- **Giving the task during orientation.** You hand over F1 while the agent is still reporting state, so Phase 0 never closes with a real stop. Let it finish and wait — orientation exists for *you*, to confirm shared state before work begins. This is **FM #9 (task-in-prompt bypass)**; the countermeasure is Step 1 — let the report land before you direct. +- **Approving by silence at the Present gate.** Skimming the plan and saying nothing is not approval — and the agent must not code without it. Read it; the whole value of the gate is the cheap catch. Coding before approval is **FM #2 (keep going)** crossed with skipping the gate; the countermeasure is Step 4's explicit go-ahead. +- **"While I'm in there, I'll fix B1."** The empty-text bug is right next to your change and tempting. Fixing it makes this two deliverables. That's **FM #2 (keep going)** / **FM #8 (redesign during implementation)**; the countermeasure is the "What I'm NOT changing" boundary in Step 3 and "1 and done." + +## You produced + +One real deliverable taken end-to-end: a tested, runtime-verified `todo done ` (Track B) or your own first feature (Track A), plus a `SESSION_NOTES.md` handoff written to be *scored* by the next session. You ran Phase 0 to a real stop, held the Present gate, kept scope to one item, and closed out cleanly — the whole loop, once, for real. The deferred B1 bug and the three near-misses you just resisted (self-assigning during orient, coding before approval, fixing B1 inline) are exactly the material Tutorial 5 turns into cautionary cases. + +## Next + +→ **Tutorial 5: Cautionary Use** *(coming in a later session)* — the gates, the 26 failure modes, "1 and done," the vertical-slice gates, and the Plan-Mode exit trap, built on the near-misses from *this* session — and when the methodology is too heavy to bother. This pointer becomes a live link to `T5_cautionary.md` when that tutorial lands. diff --git a/docs/tutorials/T2_worked_transcript.md b/docs/tutorials/T2_worked_transcript.md new file mode 100644 index 00000000..45fb2fed --- /dev/null +++ b/docs/tutorials/T2_worked_transcript.md @@ -0,0 +1,256 @@ + + +# Worked Transcript — Tutorial 2's First Session + +This is the verbatim shape of one real methodology session: building **F1 — `todo done `** on the [sample project](sample-project/), from orientation to close-out, through all six phases. [Tutorial 2](T2_first_session.md) walks you through running it yourself; this file is what "a good run looks like." + +- **Track B** learners (bundled sample): replay these steps in your sandbox — your tool output should match within a line or two. +- **Track A** learners (your own repo): read this as the reference while you take *your own* first backlog item through the same six phases. + +> **The session is `Session 1`.** Tutorial 1 *installed* the framework; it deliberately ran no feature work (T1 Step 6). So this is the project's first real session — which is why Phase 3A (evaluate the predecessor) is skipped below: there is no predecessor yet. + +The operating procedure is [`SESSION_RUNNER.md`](../../starter-kit/SESSION_RUNNER.md); its phases wrap the [six phases](../../ITERATIVE_METHODOLOGY.md#the-6-phases) of the flight manual. The task — *"Implement F1"* — maps to the [Development workstream](../../workstreams/DEVELOPMENT_WORKSTREAM.md). Nothing below is restated from those docs; the transcript *shows the procedure being followed* and links to it. + +--- + +## Phase 0 — Orient *(change nothing, read only)* + +The agent read `CLAUDE.md` when the session began; its first act is to orient, **not** to start coding. It works through the Phase 0 checklist: + +1. Read `SAFEGUARDS.md` in full — blast-radius limit (≤5 files/commit), the build-equivalent rule, the one-deliverable rule. +2. Read `SESSION_NOTES.md` → **ACTIVE TASK: none.** This is Session 1. +3. No GitHub repo, so read `BACKLOG.md`. Top item is **F1 — `todo done `**. +4. Workspace state: + +```text +$ git status +On branch main +nothing to commit, working tree clean + +$ git log --oneline -1 +a1b2c3d start: sample todo CLI (+ methodology framework, Tutorial 1) +``` + +5. Ran `python3 methodology_dashboard.py` → dashboard refreshed; methodology-compliance score is non-zero (T1 installed the files). +6. **Ghost-session check:** `SESSION_NOTES.md` documents no sessions; `git log` shows only the setup commit. No undocumented work. Clean. +7. **Build equivalent, baseline** — the gate before any change is green tests: + +```text +$ python -m pytest -q +....... [100%] +7 passed in 0.01s +``` + +**Orientation report to the operator:** *On `main`, clean tree. Session 1 — no prior session. Backlog top item is F1 (`todo done `). Baseline: 7 tests pass. Dashboard healthy. Awaiting a task.* + +→ **STOP.** Phase 0 ends by waiting for the operator. The agent does **not** assume "the backlog says F1, so I'll start." (That assumption is [FM #1](../../starter-kit/SESSION_RUNNER.md#known-failure-modes).) + +--- + +## Phase 1 — Receive Task + +Operator: **"Implement F1 — `todo done `."** + +The agent states its understanding back: + +> *I'm going to implement one deliverable — the `todo done ` command — following the Development workstream. I'll close out when that's done.* + +### 1B — Claim the Session + +**Mandatory, before any technical work.** A stub is written to `SESSION_NOTES.md` **first**, so even a crash leaves a trace: + +```markdown +### What Session 1 Did +**Deliverable:** Implement F1 — `todo done ` (IN PROGRESS) +**Started:** (timestamp) +**Status:** Session claimed. Work beginning. +``` + +--- + +## Phase 2 — Execute + +The agent reads the [Development workstream](../../workstreams/DEVELOPMENT_WORKSTREAM.md) and follows its phases, respecting the hard gates. + +### Research + +- **Expected behavior:** `todo done ` marks the task with that id complete and persists it. **Current behavior:** there is no such command (`add`, `list` only). +- **Read the code that will change** (not the description — the implementation): `todo.py`. The data model *already* carries a `done` flag (`add_todo` sets `"done": False`; `render` prints `[x]` when true). So the gap is a *command*, not a data-model change — `mark_done` core + a `cmd_done` shell + one parser entry. +- **Acceptance criteria:** marking an existing id sets `done=True` and saves; an unknown id is a clean non-zero error, not a crash; the existing 7 tests stay green. +- **Edge cases:** unknown id; already-done id (should be idempotent). +- **Scope challenge.** Reading `add_todo` surfaces **B1** (the NOTE in the code: empty text is accepted without validation). It is tempting to "just fix that while I'm here." → **Caught: that is a second deliverable.** B1 gets its own session with its own test. F1 only. *(This near-miss is one of Tutorial 5's cautionary cases.)* + +### Create — the implementation plan *(design before code)* + +```markdown +## What I'm changing +- todo.py: add `mark_done(todos, todo_id)` — pure core, no I/O, returns the + todo or None. Idempotent. +- todo.py: add `cmd_done(args)` — load → mark_done → save; unknown id → stderr + exit 1. +- todo.py: register the `done` subparser with one positional `id` (type=int). + +## What I'm NOT changing (scope boundary) +- add_todo validation (B1) — separate session. +- render / load_todos / save_todos — already support the `done` flag. + +## Test plan (test-first) +- mark_done sets the flag and returns the todo; leaves others untouched. +- mark_done on an already-done task is idempotent. +- mark_done unknown id → None, list unchanged. +- main(["done","1"]) persists done=True and exits 0. +- main(["done","42"]) on a missing id exits 1. + +## Verification +1. The 5 new tests fail before the change (red), pass after (green). +2. The original 7 tests still pass (no regression). +3. Manual CLI run: add → done → list shows [x]; unknown id errors cleanly. +``` + +### Present — **the gate** *(STOP and get approval)* + +The agent presents the plan above and **stops**. No code yet. + +> *Here is the plan for F1: a `mark_done` core function, a `cmd_done` shell, one parser entry, five tests written first. B1 (empty-text validation) is explicitly out of scope. Approve before I implement?* + +Operator: **"Approved."** + +→ This is the highest-ROI gate in the methodology: a flawed plan caught here costs zero implementation effort. The agent did **not** start coding when the plan felt obvious — implementing before this approval would be skipping the [Present gate](../../ITERATIVE_METHODOLOGY.md#the-6-phases). + +### Implement — test-first *(red → green)* + +**Red.** The five tests go in `test_done.py` *before* the implementation, and are run to prove they fail for the right reason: + +```text +$ python -m pytest test_done.py -q +... +todo: error: argument command: invalid choice: 'done' (choose from 'add', 'list') +... +5 failed in 0.25s +``` + +Red confirmed: `mark_done` does not exist and `done` is not a subcommand. (A test that passes before you write the feature is testing nothing.) + +**Green.** The plan's three edits to `todo.py`, applied verbatim: + +```diff ++def mark_done(todos: list[dict], todo_id: int) -> dict | None: ++ """Mark the todo with `todo_id` complete and return it; None if no such id.""" ++ for t in todos: ++ if t["id"] == todo_id: ++ t["done"] = True ++ return t ++ return None +@@ ++def cmd_done(args: argparse.Namespace) -> int: ++ store = _store_path(args) ++ todos = load_todos(store) ++ todo = mark_done(todos, args.id) ++ if todo is None: ++ print(f"no todo with id {args.id}", file=sys.stderr) ++ return 1 ++ save_todos(store, todos) ++ print(f"done #{todo['id']}: {todo['text']}") ++ return 0 +@@ ++ p_done = sub.add_parser("done", help="mark a todo complete") ++ p_done.add_argument("id", type=int, help="the id of the todo to complete") ++ p_done.set_defaults(func=cmd_done) +``` + +Re-run the **full** build equivalent (not just the new file — watch for regressions): + +```text +$ python -m pytest -q +............ [100%] +12 passed in 0.02s +``` + +7 original + 5 new = 12. No regression. + +--- + +## Phase 3 — Close Out *(automatic; do not ask "shall I continue?")* + +### 3A — Evaluate the predecessor's handoff + +**Skipped — this is Session 1.** There is no previous handoff to score. (From Session 2 on, this step comes first and scores the prior session 1–10.) + +### 3B — Self-assess + +Research before code: yes. Read the implementation, not just the backlog line: yes — that is what revealed the `done` flag already existed and kept the change to ~30 lines. Stakeholder corrections: 0. Scope held (B1 deferred): yes. + +### 3C — Document Learnings + +The sample project is an *adopter* (it copied `SESSION_RUNNER.md`), so any project learning is recorded in its `CLAUDE.md` → Project-Specific Methodology Adaptations — **not** in the synced files. One worth keeping: *the core stays I/O-free — `cmd_done` persists, `mark_done` must not*, so the next `done`-style command follows the same split. Nothing framework-level to record this session. + +### 3D — Handoff notes + +`SESSION_NOTES.md` stub is overwritten with the full handoff: + +```markdown +### What Session 1 Did +**Deliverable:** F1 — `todo done ` (DONE) +**What was done:** mark_done() + cmd_done() + `done` subparser in todo.py; 5 tests + in test_done.py. Commit (hash). 12/12 tests green; CLI smoke-tested. +**What's next:** F2 — `todo rm ` (BACKLOG). Decide id-reuse policy after delete + (see test_add_reuses_max_id_plus_one_after_gaps in test_todo.py). +**Key files:** todo.py:57 mark_done (core), todo.py:103 cmd_done (shell), + todo.py:127 done subparser. test_done.py (all F1 tests). +**Gotchas:** core stays I/O-free — cmd_done persists, mark_done must not. + B1 (empty-text validation) is a KNOWN open item, deliberately NOT touched this session. +**Self-assessment:** 0 corrections; scope held; runtime-verified. 9/10. +``` + +### 3E — Runtime smoke test + +The deliverable changes runtime behavior (a new subcommand and dispatch), so "tests pass" is necessary but not sufficient — the app is actually run: + +```text +$ python3 todo.py --file demo.json add "write the report" +added #1: write the report +$ python3 todo.py --file demo.json done 1 +done #1: write the report +$ python3 todo.py --file demo.json list + 1 [x] write the report +$ python3 todo.py --file demo.json done 99 +no todo with id 99 # exit status 1 +``` + +The feature is *active*, not just compiled. (Skipping this is [FM #24, build-passes-ship-it](../../starter-kit/SESSION_RUNNER.md#known-failure-modes).) + +### 3F — Commit *(one fix, one commit)* + +```text +$ git commit -am "feat(todo): add `done ` to mark a task complete (F1)" +``` + +### 3G — Report and STOP + +Deliverable summarized, self-assessment given, next session pointed at F2. + +→ **The session is over.** The agent does **not** continue to F2, and does **not** fix B1. "1 and done." ([FM #2](../../starter-kit/SESSION_RUNNER.md#known-failure-modes) is the urge to keep going.) + +--- + +## Near-misses this session caught *(these feed Tutorial 5)* + +1. **"The backlog says F1 — I'll just start."** Caught at the end of Phase 0: orientation ends by *waiting for the operator*, not by self-assigning. → FM #1. +2. **"While I'm in `add_todo`, I'll fix the empty-text bug (B1)."** Caught in Research / scope-challenge: that is a second deliverable. → FM #2 / FM #8, "1 and done." +3. **"The plan is obvious — I'll skip straight to coding."** Caught at the Present gate: no implementation before explicit approval. + +## What this session produced + +One shipped, tested, runtime-verified feature — `todo done ` — reached through all six phases with zero stakeholder corrections, the B1 scope-creep temptation deferred to its own session, and a handoff a Session 2 could act on without re-discovery. That is the unit the methodology optimizes: **one deliverable, done well, set up to compound.** + +→ Back to **[Tutorial 2: Your First Session, End-to-End](T2_first_session.md)** to run it yourself. From 19fc9993594778ea601d0d7ffd8be01fcd584248 Mon Sep 17 00:00:00 2001 From: "R. Mark Sharp" Date: Sun, 21 Jun 2026 01:51:37 -0500 Subject: [PATCH 6/7] docs(tutorials): add T5 Cautionary Use + publish core trio (P4) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Completes the tutorial core trio (T1 · T2 · T5). T5 is built on the three near-misses recorded in T2's worked transcript: it has the learner consult (not memorize) the failure-mode list and gates, deliberately provoke Phase 0 and the scope boundary and watch them hold, recognize the Plan-Mode exit trap and the vertical-slice masquerade (FM #26), and make an explicit use/don't-use call via §When to Use / HOW_TO_USE §Troubleshooting. Cite, don't restate: every FM is cited by number and every gate/section by anchor; no canonical list is forked. Wiring: T2 "Next" is now a live link; the tutorials index and the root README mark the trio published. Adversarially verified (5-dimension workflow): all FM/gate numbers, link anchors, counts (26 FMs / 12 gates / four slice gates), and running-example facts (F2/B1, 12-passed post-F1 baseline) confirmed; one cross-doc status drift in root README fixed. bin/tests.sh 28/28 green; bin/sync --dry-run references no tutorials (non-distribution per plan §6). Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 2 +- docs/tutorials/README.md | 12 ++-- docs/tutorials/T2_first_session.md | 2 +- docs/tutorials/T5_cautionary.md | 90 ++++++++++++++++++++++++++++++ 4 files changed, 98 insertions(+), 8 deletions(-) create mode 100644 docs/tutorials/T5_cautionary.md diff --git a/README.md b/README.md index c4e436a9..3ad5bbb8 100644 --- a/README.md +++ b/README.md @@ -143,7 +143,7 @@ Expand any project card to see health breakdown by dimension, risk factors, git ## Tutorials -New to the methodology? The **[tutorials](docs/tutorials/)** are a hands-on, progressive learning track — install the framework, run a real session end to end, and learn where the guardrails catch you. Each lesson has you *do* one thing against a real project (your own repo, or the bundled [sample project](docs/tutorials/sample-project/)), with a checkpoint at every step. The core trio (Setup → First Session → Cautionary Use) is in progress; see the **[series index](docs/tutorials/)** for the full curriculum. +New to the methodology? The **[tutorials](docs/tutorials/)** are a hands-on, progressive learning track — install the framework, run a real session end to end, and learn where the guardrails catch you. Each lesson has you *do* one thing against a real project (your own repo, or the bundled [sample project](docs/tutorials/sample-project/)), with a checkpoint at every step. The core trio (Setup → First Session → Cautionary Use) is published; see the **[series index](docs/tutorials/)** for the full curriculum. ## Repository Structure diff --git a/docs/tutorials/README.md b/docs/tutorials/README.md index 20831316..8ac1df25 100644 --- a/docs/tutorials/README.md +++ b/docs/tutorials/README.md @@ -4,11 +4,11 @@ A hands-on, progressive learning track for the Iterative Session Methodology. Th docs *define* the framework — this one makes you *do* it, one thing at a time, against a real project, with a checkpoint after each step. -> **Status:** [Tutorial 1: Setup & First Bootstrap](T1_setup.md) and -> [Tutorial 2: Your First Session, End-to-End](T2_first_session.md) are published — T2 ships with a -> [worked transcript](T2_worked_transcript.md) of a real session against the sample project. The -> [tutorial template](TUTORIAL_TEMPLATE.md) and [sample project](sample-project/) are in place; -> T5 lands in a later session. The curriculum below shows what's done and what's coming. +> **Status:** The **core trio is published** — [T1: Setup & First Bootstrap](T1_setup.md), +> [T2: Your First Session, End-to-End](T2_first_session.md) (with a +> [worked transcript](T2_worked_transcript.md) of a real session against the sample project), and +> [T5: Cautionary Use](T5_cautionary.md). The [tutorial template](TUTORIAL_TEMPLATE.md) and +> [sample project](sample-project/) are in place. The curriculum below shows what's done and what's coming. ## Why bother? @@ -56,7 +56,7 @@ The **core trio (T1 · T2 · T5)** is the first cut; the rest is a roadmap. |---|----------|--------------------|:-------------:| | [T1](T1_setup.md) | Setup & First Bootstrap | Install the framework into a project: root files, `CLAUDE.md` protocol block, task tracking, dashboard | ✅ **published** | | [T2](T2_first_session.md) | Your First Session, End-to-End | Run one full 6-phase pass to one deliverable — with Phase 0 Orient and the Present gate front and center | ✅ **published** | -| T5 | Cautionary Use | Read the gates, the 26 failure modes, "1 and done", the vertical-slice gates, and the Plan-Mode exit trap — and know when the methodology is too heavy | ✅ planned | +| [T5](T5_cautionary.md) | Cautionary Use | Read the gates, the 26 failure modes, "1 and done", the vertical-slice gates, and the Plan-Mode exit trap — and know when the methodology is too heavy | ✅ **published** | | T3 | The Compounding Loop | Run the handoff + scoring loop and watch session N+1 improve | roadmap | | T4 | Choosing & Adapting a Workstream | Pick the right workstream; spin up a custom one | roadmap | | T6 | Multi-Session Campaigns | Carry one deliverable across many sessions | roadmap | diff --git a/docs/tutorials/T2_first_session.md b/docs/tutorials/T2_first_session.md index c2e333a6..75827d7c 100644 --- a/docs/tutorials/T2_first_session.md +++ b/docs/tutorials/T2_first_session.md @@ -113,4 +113,4 @@ One real deliverable taken end-to-end: a tested, runtime-verified `todo done **Objective:** Read the methodology's guardrails the way they're meant to be read — the gates, the 26 failure modes, "1 and done," the vertical-slice gates, and the Plan-Mode exit trap as a reference the procedure enforces *for* you — and judge the one case where the right move is not to use the methodology at all. +> **Prerequisites:** [Tutorial 2: Your First Session, End-to-End](T2_first_session.md) — you need a session you've actually run, because its near-misses are this tutorial's raw material. New here? Start at the [series index](README.md). +> **Time:** ~20 minutes +> **What you'll produce:** A near-miss you catch on purpose — you deliberately push a session toward a gate, watch the gate hold, and record the catch — plus a written "use it / don't use it" verdict for one real task. +> **Track:** Pick one and stick with it for this pass — +> **A** (your own repo): probe the gates on a real backlog item; your [Tutorial 2](T2_first_session.md) run is the reference. +> **B** ([sample project](sample-project/)): probe them on the next backlog item, **F2 — `todo rm `**, the item your Tutorial 2 handoff pointed at. + +## Why this matters + +The earlier tutorials had you *avoid* the near-misses. This one has you *provoke* them — because the guardrails are the actual product, and you only trust a guardrail you've felt hold. The deepest cautionary fact in the framework is that the discipline is perishable: 14 consecutive clean sessions can collapse within hours once steps start getting shaved off. Knowing the gates by name is how you notice the shaving before it cascades. The case is documented, not asserted: + +- [Protocol Erosion](../../ITERATIVE_METHODOLOGY.md#protocol-erosion) — how a working methodology degrades, and why "this step doesn't apply to my session" is the erosion itself. +- [When to Use This Methodology](../../ITERATIVE_METHODOLOGY.md#when-to-use-this-methodology) — the explicit *do-not-use* list, so you don't burn the overhead on a one-off. +- [Evidence](../../README.md#evidence) — what holding the line actually changed. + +This tutorial does not restate the gates, the 26 failure modes, or the vertical-slice gates — those live in the [cockpit checklist](../../starter-kit/SESSION_RUNNER.md) and the [flight manual](../../ITERATIVE_METHODOLOGY.md), one source of truth. It makes you *use* them as a reference and *test* that they hold. + +## Before you start + +You need a completed Tutorial 2 run. Re-open two things: the [worked transcript's near-misses](T2_worked_transcript.md#near-misses-this-session-caught-these-feed-tutorial-5) (the three catches), and your own `SESSION_NOTES.md` handoff from that session — the one that named **F2** as next and flagged **B1** (empty-text validation) as a known, deliberately-untouched item. + +```sh +# Track B, from your sandbox copy of the sample project: +python -m pytest # expect: 12 passed (F1 shipped in Tutorial 2) +grep -nE "F2|B1" BACKLOG.md # both are still open work +``` + +**Checkpoint:** You can name the three near-misses from your own run, and you can see that F2 and B1 are still open. You are about to start a *fresh* session and deliberately steer it at a gate. + +## Steps + +The first step is reading; the rest is provoking a real session and watching the procedure refuse to break. Don't skip ahead — Step 1 gives you the names you'll point at in Steps 2–4. + +### 1. Map your own near-misses to their failure modes — consult, don't memorize + +Open the [Known Failure Modes](../../starter-kit/SESSION_RUNNER.md#known-failure-modes) table and the [12 quality gates](../../ITERATIVE_METHODOLOGY.md#quality-gates-summary). For each of the three near-misses your Tutorial 2 session caught, find the row that names it and the countermeasure that stopped it. + +**Expected result:** Three clean mappings — "the backlog says F1, I'll just start" → **[FM #1](../../starter-kit/SESSION_RUNNER.md#known-failure-modes)** (Phase 0 stop); "I'll fix B1 while I'm in there" → **[FM #2](../../starter-kit/SESSION_RUNNER.md#known-failure-modes) / [#8](../../starter-kit/SESSION_RUNNER.md#known-failure-modes)** ("1 and done"); "the plan's obvious, I'll just code" → the **Present gate** ([Quality Gate #6](../../ITERATIVE_METHODOLOGY.md#quality-gates-summary)). +**Checkpoint:** You can point at the exact row for each. Notice what you did *not* have to do: memorize all 26. The list is a reference you consult; the gates enforce the behavior whether or not you can recite it. + +### 2. Provoke Phase 0 — hand over a task during orientation + +Start a brand-new session against the project. While the agent is still orienting — before it has reported state and stopped — interrupt with a task: *"Implement F2 — `todo rm `."* You are deliberately doing the thing Tutorial 2 told you not to: handing work in mid-orient. + +**Expected result:** The session does **not** drop orientation and start coding. It finishes all of Phase 0, reports state, and waits — a task in the prompt does not complete Phase 0. +**Checkpoint:** The gate held: you pushed and it still stopped for you. Write that down in `SESSION_NOTES.md` ("Caught: task-in-prompt during orient; Phase 0 held"). That recorded catch is **[FM #9](../../starter-kit/SESSION_RUNNER.md#known-failure-modes)**'s countermeasure working. (If it *did* start editing, the protocol isn't loaded — re-check [Tutorial 1 Step 2/6](T1_setup.md).) + +### 3. Provoke the scope boundary — "while you're in there, also fix B1" + +Now approve F2 the normal way, and at the plan/Present beat add the tempting rider: *"and while you're in `todo.py`, just fix the empty-text bug B1 too."* B1 is right next to your change and trivial. Watch what a session on the procedure does with a second deliverable smuggled in. + +**Expected result:** It declines to bundle — B1 is named as out of scope and routed to its own session, exactly as your Tutorial 2 plan deferred it. One intent ships; the other is handed off. +**Checkpoint:** Scope held against a direct request to break it. That's "1 and done" — **[FM #2](../../starter-kit/SESSION_RUNNER.md#known-failure-modes)** crossed with **[FM #8](../../starter-kit/SESSION_RUNNER.md#known-failure-modes)** (redesign-during-implementation). Record this catch too. (Two small things in one session is still two deliverables.) + +### 4. Recognize the two traps you can't easily stage + +Some gates you won't trip in a tutorial, but you must recognize them on sight: + +- **The Plan-Mode exit trap.** When a multi-phase plan arrives in the prompt under Plan Mode's auto-preamble *"Implement the following plan,"* that wording is **not** a go-ahead to code. The plan is a draft until it's written to `docs/planning/` with an evidence-based inventory; planning and implementation are separate sessions. See the [Phase 1 trap warning](../../starter-kit/SESSION_RUNNER.md#phase-1-receive-task), **[FM #19](../../starter-kit/SESSION_RUNNER.md#known-failure-modes)** (plan-mode bypass) and **[FM #18](../../starter-kit/SESSION_RUNNER.md#known-failure-modes)** (planning-to-implementation bleed). +- **The vertical-slice masquerade.** "1 and done" has exactly one sanctioned way to ship more than one layer: a *verified vertical slice* — **one capability** end to end under four mandatory gates (a pre-declared contract, a checkpoint commit at every layer boundary, full verification at every boundary, and faithful per-surface verification). It is never a license to bundle two capabilities. Bundling F2 **and** B1 and calling it "a slice" is **[FM #26](../../starter-kit/SESSION_RUNNER.md#known-failure-modes)**. The test: does one prior-session plan-mode contract enumerate exactly this layer set, all of the *same* capability? See [§Vertical Slice Sessions](../../starter-kit/SESSION_RUNNER.md#vertical-slice-sessions). + +**Expected result:** You can state, in one sentence each, why "Implement the following plan" doesn't mean start coding, and why F2+B1 is not a slice. +**Checkpoint:** You can tell a legitimate slice (data + service + client + tests of *one* capability, four gates met) from a mega-session wearing the slice costume (two capabilities, or a plan plus its code). + +### 5. Make the "don't use it" call + +Take one real task you actually have and run it through the [When to Use](../../ITERATIVE_METHODOLOGY.md#when-to-use-this-methodology) test. Is it repeated work where quality compounds and a stakeholder approves the output — or a genuine one-off where the overhead exceeds the work? Write a one-line verdict. + +**Expected result:** A written call — e.g., *"One-off config tweak, no repetition, no stakeholder → skip the methodology, just do it"* or *"First of ~6 similar migrations → use it; Session 1's overhead pays off by Session 3."* +**Checkpoint:** You produced a use/don't-use decision grounded in the actual criteria, not a reflex to always run the full protocol. Running all six phases on a trivial one-off is its own failure — see [HOW_TO_USE.md "The methodology feels too heavy for this task"](../../HOW_TO_USE.md#the-methodology-feels-too-heavy-for-this-task). + +## Common mistakes + +Cite the failure mode by number; link the list, don't paste it. +(Full list: [Known Failure Modes](../../starter-kit/SESSION_RUNNER.md#known-failure-modes).) + +- **Trying to memorize the 26 failure modes.** They are a reference you consult at the moment of temptation, not a quiz. Operating from a half-remembered gist is itself **FM #3 (skim documents)** — the countermeasure is to open the table and read the row, the way you did in Step 1. +- **"This step doesn't apply to my session."** The single most important cautionary line in the framework: that thought *is* the erosion. This is **FM #17 (protocol erosion)** — every step exists because a session failed without it, and the vertical-slice allowance *adds* a gate, it never removes one. When you catch yourself shaving a step, see [Degradation Detection](../../starter-kit/SESSION_RUNNER.md#degradation-detection). +- **Calling a two-capability bundle "a vertical slice."** Pre-declaring a contract for *one* capability's layers is the slice; reaching for the slice vocabulary to ship F2 and B1 together is **FM #26 (mega-session masquerading as a vertical slice)**. One capability, one prior contract, exactly that layer set — or split it. + +## You produced + +Two near-misses you caught on purpose — recorded in `SESSION_NOTES.md` as gates that held when you deliberately pushed on them (task-in-prompt during orient; a second deliverable smuggled into the Present beat) — and a written use/don't-use verdict for one real task. You now read the failure-mode list and the gates the way they're meant to be read: as a reference the procedure enforces for you, not a thing to recite. And you know the one task profile where the disciplined move is to *not* use the methodology at all. + +## Next + +That's the **core trio (T1 · T2 · T5)** — installed, run once for real, and stress-tested. From here the [curriculum](README.md#curriculum) maps the roadmap: **T3 — The Compounding Loop** (run the handoff-and-scoring loop across sessions and watch session N+1 beat session N) is the natural continuation when it lands. For now, take the use/don't-use judgment from Step 5 to a real project — the methodology earns its keep on the work you'd otherwise repeat without learning from. From 09b0aa929e7e9b6c4921a9861bba88560e2da7f5 Mon Sep 17 00:00:00 2001 From: "R. Mark Sharp" Date: Sun, 21 Jun 2026 02:17:09 -0500 Subject: [PATCH 7/7] docs(tutorials): fix v2.8 sync drift + cite-don't-restate (pre-PR review) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A pre-PR adversarial review (5 lenses) of the core trio against the post-v2.8 canonical caught five confirmed defects; this fixes all five. T1 (Setup): - Step 1 Expected result/Checkpoint described the dead pre-v2.8 3-file bin/sync behavior; rewrite to the full-corpus model and cite bin/_manifest.py as the source of truth. - Step 3 told the learner to manually copy CHANGELOG.md/ROADMAP.md that post-v2.8 bin/sync now seeds; make it sync-aware (author BACKLOG.md, confirm the seeded files). - Before-you-start Track B: ../methodology/bin/sync dangled after cd ~/todo-practice; capture the checkout in $METH and point sync at it (--source=github does not escape the local-script requirement). T5 (Cautionary): - Drop the inline four-gate enumeration (it restated the vertical-slice gates line 19 promises not to restate); cite §Vertical Slice Sessions. - Tighten the Plan-Mode trap blurb to recognition + FM #18/#19 citation, dropping the restated docs/planning procedure. The drift surfaced because the branch predated v2.8 (bin/sync full-corpus expansion); rebasing onto v2.8 made it live and the review caught it. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/tutorials/T1_setup.md | 25 +++++++++++++++---------- docs/tutorials/T5_cautionary.md | 4 ++-- 2 files changed, 17 insertions(+), 12 deletions(-) diff --git a/docs/tutorials/T1_setup.md b/docs/tutorials/T1_setup.md index efdb8342..61e4f31f 100644 --- a/docs/tutorials/T1_setup.md +++ b/docs/tutorials/T1_setup.md @@ -30,8 +30,10 @@ python3 --version # Python 3.8+ cd your-project git switch -c methodology-practice ``` -- **Track B — the bundled sample.** Copy the sample *out* of the methodology repo into a throwaway location, so your practice edits never touch the methodology checkout, and make it a standalone repo: +- **Track B — the bundled sample.** Copy the sample *out* of the methodology repo into a throwaway location, so your practice edits never touch the methodology checkout, and make it a standalone repo. Run the copy from inside your methodology checkout and capture where that checkout is — you'll point `bin/sync` at it in Step 1: ```sh + # from inside your methodology checkout (wherever you cloned it): + METH=$PWD cp -r docs/tutorials/sample-project ~/todo-practice cd ~/todo-practice git init -q && git add -A && git commit -qm "start: sample todo CLI" @@ -45,20 +47,21 @@ Each step is one action and its expected result. Don't skip ahead — the final ### 1. Copy the methodology files into your project -You have two ways to do this; both are first-class. The scripted path is fastest if you have a local `methodology/` checkout (Track B learners already do — it's where the sample came from). +You have two ways to do this; both are first-class. The scripted path is fastest if you have a local `methodology/` checkout (Track B learners already do — it's where the sample came from). Point the command at that checkout: Track B uses the `$METH` it set in "Before you start"; Track A learners who keep the portfolio layout (projects as siblings of the checkout) can use the relative `../methodology/` form. `bin/sync` runs from the local checkout regardless of `--source` (the script must exist on disk; `--source` only changes where the *contents* are read from). ```sh # Scripted (committed mode is the default): -../methodology/bin/sync . +"$METH"/bin/sync . # Track B — $METH is your methodology checkout +../methodology/bin/sync . # Track A — a sibling checkout, per the portfolio layout -# …or, with no sibling checkout, pull from GitHub (needs the gh CLI): -../methodology/bin/sync . --source=github +# …or pull canonical contents from GitHub instead of the local checkout (needs the gh CLI): +"$METH"/bin/sync . --source=github ``` For the manual path, or the difference between committed and ignored modes, see [`BOOTSTRAP.md` §Setup with `bin/sync`](../../starter-kit/BOOTSTRAP.md#setup-with-binsync-recommended) and [§Setup by manual copy](../../starter-kit/BOOTSTRAP.md#setup-by-manual-copy-always-valid). -**Expected result:** `bin/sync` copies `SESSION_RUNNER.md`, `SAFEGUARDS.md`, and `methodology_dashboard.py` into the project. -**Checkpoint:** `ls SESSION_RUNNER.md SAFEGUARDS.md methodology_dashboard.py` lists all three. +**Expected result:** `bin/sync` copies the **full methodology corpus** into the project — the operating files at the root (`SESSION_RUNNER.md`, `SAFEGUARDS.md`, `RECOMMENDED_SKILLS.md`, the `CONTEXT_TEMPLATE.md`/`CLAUDE_TEMPLATE.md` templates, `BOOTSTRAP.md`, `methodology_dashboard.py`) and the framework (`ITERATIVE_METHODOLOGY.md`, `HOW_TO_USE.md`, `workstreams/`) under `docs/methodology/` — and *seeds* `SESSION_NOTES.md`, `CHANGELOG.md`, and `ROADMAP.md` at the root when they're absent. The exact mapping is defined once in [`bin/_manifest.py`](../../bin/_manifest.py). +**Checkpoint:** the operating files are at your project root and the framework is under `docs/methodology/` — `ls SESSION_RUNNER.md SAFEGUARDS.md methodology_dashboard.py` and `ls docs/methodology/` both succeed. ### 2. Tell your agent to use it — the SESSION PROTOCOL block @@ -80,10 +83,12 @@ The full block (with the three rules you'll be tempted to violate) and the `CLAU Open work, completed history, and future plans live in three separate files so the one the agent reads at session start (`BACKLOG.md`) stays scannable. See [`BOOTSTRAP.md` §Step 3](../../starter-kit/BOOTSTRAP.md#step-3-create-your-task-tracking-files). -- **Track B:** the sample already ships a [`BACKLOG.md`](sample-project/BACKLOG.md) — that *is* your project backlog. Its first item, `F1: todo done `, is exactly the feature you'll build end-to-end in Tutorial 2. Copy the `CHANGELOG.md` and `ROADMAP.md` templates from `starter-kit/` to the project root. -- **Track A:** create a `BACKLOG.md` with your open items only (no completed work), and copy the `CHANGELOG.md` / `ROADMAP.md` templates from `starter-kit/`. +Step 1's `bin/sync` already *seeded* `CHANGELOG.md` and `ROADMAP.md` at your root (they're SEED files — written once, then yours to edit). `BACKLOG.md` is the one it deliberately doesn't create: it's adopter-owned, so it's the file you author here. (If you took the manual copy path instead of `bin/sync`, copy `CHANGELOG.md`/`ROADMAP.md` from `starter-kit/` per [`BOOTSTRAP.md` §Step 3](../../starter-kit/BOOTSTRAP.md#step-3-create-your-task-tracking-files).) -**Expected result:** three files at the root — `BACKLOG.md` (open items only), `CHANGELOG.md`, `ROADMAP.md`. +- **Track B:** the sample already ships a [`BACKLOG.md`](sample-project/BACKLOG.md) — that *is* your project backlog. Its first item, `F1: todo done `, is exactly the feature you'll build end-to-end in Tutorial 2. Confirm the seeded `CHANGELOG.md` and `ROADMAP.md` are present. +- **Track A:** author a `BACKLOG.md` with your open items only (no completed work); `CHANGELOG.md` and `ROADMAP.md` are already at your root from Step 1. + +**Expected result:** three files at the root — `BACKLOG.md` (open items only, hand-authored) plus the seeded `CHANGELOG.md` and `ROADMAP.md`. **Checkpoint:** `BACKLOG.md` lists only actionable work and reads in under a minute; `CHANGELOG.md` and `ROADMAP.md` both exist. ### 4. Record your build equivalent diff --git a/docs/tutorials/T5_cautionary.md b/docs/tutorials/T5_cautionary.md index 95f15ddc..442a35f1 100644 --- a/docs/tutorials/T5_cautionary.md +++ b/docs/tutorials/T5_cautionary.md @@ -59,8 +59,8 @@ Now approve F2 the normal way, and at the plan/Present beat add the tempting rid Some gates you won't trip in a tutorial, but you must recognize them on sight: -- **The Plan-Mode exit trap.** When a multi-phase plan arrives in the prompt under Plan Mode's auto-preamble *"Implement the following plan,"* that wording is **not** a go-ahead to code. The plan is a draft until it's written to `docs/planning/` with an evidence-based inventory; planning and implementation are separate sessions. See the [Phase 1 trap warning](../../starter-kit/SESSION_RUNNER.md#phase-1-receive-task), **[FM #19](../../starter-kit/SESSION_RUNNER.md#known-failure-modes)** (plan-mode bypass) and **[FM #18](../../starter-kit/SESSION_RUNNER.md#known-failure-modes)** (planning-to-implementation bleed). -- **The vertical-slice masquerade.** "1 and done" has exactly one sanctioned way to ship more than one layer: a *verified vertical slice* — **one capability** end to end under four mandatory gates (a pre-declared contract, a checkpoint commit at every layer boundary, full verification at every boundary, and faithful per-surface verification). It is never a license to bundle two capabilities. Bundling F2 **and** B1 and calling it "a slice" is **[FM #26](../../starter-kit/SESSION_RUNNER.md#known-failure-modes)**. The test: does one prior-session plan-mode contract enumerate exactly this layer set, all of the *same* capability? See [§Vertical Slice Sessions](../../starter-kit/SESSION_RUNNER.md#vertical-slice-sessions). +- **The Plan-Mode exit trap.** When a multi-phase plan arrives under Plan Mode's auto-preamble *"Implement the following plan,"* that wording is **not** a go-ahead to code — it is the [Plan-Mode exit trap](../../starter-kit/SESSION_RUNNER.md#phase-1-receive-task) (**[FM #19](../../starter-kit/SESSION_RUNNER.md#known-failure-modes)** plan-mode bypass, **[FM #18](../../starter-kit/SESSION_RUNNER.md#known-failure-modes)** planning-to-implementation bleed). Recognize it; planning and implementation are separate sessions. +- **The vertical-slice masquerade.** "1 and done" has exactly one sanctioned way to ship more than one layer: a *verified vertical slice* — **one capability** end to end under the four mandatory gates defined in [§Vertical Slice Sessions](../../starter-kit/SESSION_RUNNER.md#vertical-slice-sessions). It is never a license to bundle two capabilities. Bundling F2 **and** B1 and calling it "a slice" is **[FM #26](../../starter-kit/SESSION_RUNNER.md#known-failure-modes)**. The test: does one prior-session plan-mode contract enumerate exactly this layer set, all of the *same* capability? **Expected result:** You can state, in one sentence each, why "Implement the following plan" doesn't mean start coding, and why F2+B1 is not a slice. **Checkpoint:** You can tell a legitimate slice (data + service + client + tests of *one* capability, four gates met) from a mega-session wearing the slice costume (two capabilities, or a plan plus its code).