docs(tutorials): hands-on learning track — core trio T1/T2/T5 + sample project by rmsharp · Pull Request #38 · KJ5HST/methodology

rmsharp · 2026-06-21T07:18:26Z

What this adds

A new hands-on, progressive tutorial track under docs/tutorials/ — the genre the existing docs gesture at but don't deliver. The manuals define the methodology; this makes you do it, one step at a time, with a checkpoint after each.

Core trio (this PR):

T1 — Setup & First Bootstrap: install the framework into a project, end to end.
T2 — Your First Session, End-to-End: run one full 6-phase pass to one deliverable, with a worked transcript of a real session against the sample project.
T5 — Cautionary Use: read the gates / 26 FMs / "1 and done" / vertical-slice gates / Plan-Mode trap as a reference, and judge when not to use the methodology.

Plus a shared TUTORIAL_TEMPLATE.md, a series README.md (index + "why bother" hook), a bundled stdlib-only todo-CLI sample project (real pytest build equivalent + a backlog that threads the trio), and discoverability wiring (README §Tutorials; a BOOTSTRAP pointer). T3/T4/T6/T7/T8 are a documented roadmap in the series index — not in this cut.

Design principles (held throughout)

Cite, don't restate — tutorials link into BOOTSTRAP / SESSION_RUNNER / ITERATIVE_METHODOLOGY at the right beat; they never fork the principles, phases, or FM list.
Canonical-only, never distributed — tutorials are deliberately not in bin/_manifest.py, so bin/sync never copies them into adopter trees.
One running example threads the trio — T1 installs onto the sample, T2 builds one feature (recorded as the transcript), T5 reuses that session's near-misses as cautionary cases.
Dogfooded — each tutorial was authored as its own methodology session.

Verification

./bin/tests.sh → 51 passed, 0 failed
sample project pytest → 7 passed
non-distribution proof (bin/sync <tmp> --dry-run) → zero tutorial files in the adopter sync set
relative links + section anchors resolve against current canonical
Pre-PR adversarial review (5 lenses) against post-v2.8 canonical: 7 findings, all confirmed and fixed in the final commit — chiefly v2.8 bin/sync drift (the branch predated v2.8's full-corpus expansion) plus two cite-don't-restate tightenings in T5.

Notes for the maintainer

Rebased onto current main (v2.8); purely additive (~1k lines, no bin/ changes).
The planning doc lives fork-only (per the established branching pattern) and is not in this PR.
Per the plan, this is a candidate minor release — I can't self-assign a version or cut a release; suggest a version bump + a "What's New" entry at merge.

🤖 Generated with Claude Code

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) <noreply@anthropic.com>

- 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 KJ5HST#7). Part of tutorial-series plan §9 P1. No tutorial content yet. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

- 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) <noreply@anthropic.com>

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 KJ5HST#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) <noreply@anthropic.com>

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 <id>`) 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) <noreply@anthropic.com>

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 KJ5HST#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) <noreply@anthropic.com>

…iew) 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 KJ5HST#18/KJ5HST#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) <noreply@anthropic.com>

…ation (#39) Combined minor release covering two additive contributions that merged together at upstream/main: - Hands-on tutorial track (PR #38): new docs/tutorials/ learning layer — core trio T1/T2/T5 + worked transcript, series index, tutorial template, and a bundled sample todo-CLI project. Canonical-only learning aid; not distributed to adopters by bin/sync. - Reasoning-tier generalization (PR #39): new brand-neutral core section ITERATIVE_METHODOLOGY.md §Matching Reasoning Effort to Stakes (tier ∝ blast radius × irreversibility × compounding cost) + recommendation-layer RECOMMENDED_SKILLS.md §Reasoning Effort, cited across the heavy workstreams, SESSION_RUNNER planning sessions, and both campaigns. Bumps CLAUDE.md "Current version" to v2.9 and adds the README "What's New in v2.9" entry. No principle, phase, gate, workstream, or FM changes; FM count stays 26. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

… reasoning-tier)

Both plan docs lived only on their fork-only branches (docs/reasoning-tier-plan, docs/tutorial-series-plan) and were never merged into docs/planning/, unlike the other archived fork-only plans. Their work shipped in v2.9 (KJ5HST#39 + tutorials KJ5HST#38/KJ5HST#40). Archive them here to preserve the planning record, then prune the stale branches. Fork-only; not part of the canonical framework or any upstream PR. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

…cored 8/10 Deliverable shipped in 95ac6ea: CHANGELOG.md 66,553 B -> 34,044 B, from OVER by 1,017 to 31,492 B clear; 23 records archived to docs/archive/CHANGELOG-through-2026-08-24.md, 8 retained. Phase 3C: Learning KJ5HST#37 appended (1,413 B) -- a losslessness proof must model the permitted TRANSFORM, not only the population and the declared growth. My own independent proof read 21 of 23 archived records as corrupted because it ignored the ../../ link rebase; the tool was right and the proof was wrong. FRAMEWORK_LEARNINGS.md is a manifest SOURCE, so adopters receive this row. TWO CORRECTIONS MADE BEFORE COMMIT, BOTH TO CLAIMS I HAD ALREADY WRITTEN: 1. I asserted "context_budget.py exit 0" without measuring it -- an exit code I had read through a broken PIPESTATUS. It exits 1 (WARN), not 0: every file is under its ceiling, but the growth run (57 non-shrinking measurements vs a threshold of 10) returns WARN independently of any ceiling (context_budget.py:899-902; CLEAN/WARN/BREACH = 0/1/2 at :49). At Orient it was BREACH (2). Caught at the 3F cross-reference step, not by me at the time. 2. The receipt carried 51,678 / 13,858 / 12,250 for figures that had moved to 51,620 / 13,916 / 12,286 -- stale figures in a handoff, which is what I had just marked the predecessor down for. All six figures in the ledger entry are now cross-checked against wc -c programmatically, and iterated to a fixed point so each describes the file including itself. HANDED FORWARD, COMPUTED NOT GUESSED: HANDOFFS.md is one receipt from its ceiling -- 51,622 B against 65,536 (13,914 B clear) against a 12,288 B receipt, so one more fits and two do not, while the file holds 4 records against the --cut 3 floor, so a trim could archive exactly one. That is Learning KJ5HST#35's collision (a size ceiling meeting a fixture floor) arriving. VERIFICATION ON THE FINAL TREE: bin/tests.sh 280 rows, 279 passed / 1 failed / 0 skipped -- sole failure github source dry-run failed, Test 9's pre-existing 404, identical by name to the control at f40793c. Row-for-row against the post-trim run: zero lost, zero gained, three pairs differing, all derived counts that followed this session's own writes (fixture controls KJ5HST#37->KJ5HST#38 and S108->S109; Test 31's operands 7->8 moving together). check-links OK (88/22), check-handoff OK, --all OK (4 receipts), check-learnings OK (36 rows, 1..36). Both trim triggers silent. All 12 line citations plus 3 ranges in the receipt re-verified by re-reading each cited line against a regex of the claim: 15/15. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

…cored 8/10 Phase 2 of the record-budget reduction plan, SHIPPED (eec1cbb). Phase 3D receipt inside the 12,288 B per-record budget -- reached in seven trim passes against bin/check-handoff, RUN each time rather than estimated. WHAT THIS SESSION ANSWERED. The operator asked why this repo spends its effort trimming when three larger adopters do not. Measured read-only, same 65,536 B ceiling: this repo holds the SMALLEST ledgers of the four and is the ONLY one under the ceiling. wsfct FIRES; nprcgenekeepr FIRES on both; vscode_quarto_ext FIRES and its 1,780,187 B HANDOFFS.md (27x) cannot be parsed at all -- the bootstrap seed sentinel was never deleted, so it has ZERO shards after 216 receipts. They do not lack the symptom; they lack the measurement. The term genuinely wrong here is the RECEIPT: median 11,483 B (n=115, live + every shard) against 4,059-7,912 elsewhere. FINAL SIZES, MEASURED LAST: HANDOFFS.md 62,717 B 2,819 B clear of 65,536 front matter 6,170 CHANGELOG.md 46,506 B FRAMEWORK_LEARNINGS 65,520 B 16 B free <-- BLOCKS PHASE 3C NEXT SESSION VERIFICATION. bin/tests.sh 286/1/0 on the final tree; sole failure is Test 9's standing --source=github 404. All 16 shipped .verify.sh proofs run: 12 OK / 4 FAIL, the same four (BL-36), byte-identical to control. check-links 88/22, check-handoff, --all (5 receipts), check-learnings all OK. trim --check silent on both ledgers. context_budget.py: no file over its ceiling. TWO FORWARD ITEMS THE NEXT SESSION MUST NOT MISS, both computed: 1. A HANDOFFS.md TRIM IS DUE AND --check WILL NOT SAY SO. 2,819 B clear against recent receipts of 12,286 / 12,288 / 9,635 / 12,264 B -- the next close-out alone breaches the ceiling. --check measures the file as it stands, not as the receipt will leave it. Trim BEFORE close-out. 5 receipts against Test 34's floor of 3, so a cut can archive at most 2. 2. FRAMEWORK_LEARNINGS.md IS 16 B FROM ITS CEILING. No budget-conforming row fits: ROW_BUDGET_BYTES is 1,500 and the median row is ~1,971 B. This session's was written to 981 B specifically to fit the remaining 997, and consumed it. BL-45 carries four uncosted options; the choice is the operator's and must be made BEFORE the next session's Phase 3C, which cannot otherwise be discharged. Predecessor S108 scored 8/10 -- its next_steps (d) told me to DECIDE the module-scope assert question rather than discover it, which is what made Test 39 a test; against that, it understated a population by more than half (six shipped .verify.sh proofs, four failing -- there are 16) and shipped a receipt containing two mutually exclusive Learning counts. Self-scored 8/10. Phase 2 delivered whole including the half the ratified plan did not know was there, A2 built for a failure that had already happened and observed RED two independent ways; against that, I hit the same bare-substring bug twice in one session and grepped `set -o pipefail` where the file says `set -uo pipefail`, then reasoned for several steps from the inverted conclusion. Five findings recorded rather than absorbed: BL-42 (the trimmer still generates the fat pointer block), BL-43 (six pipefail-flaky assertions, enumerated), BL-44 (check-learnings prints a range it never measured), BL-45, BL-46. Canonical-only. Nothing distributed except FRAMEWORK_LEARNINGS.md, which IS a manifest source -- adopters receive Learning KJ5HST#38 at their next bin/sync. NO OUTWARD-FACING ACTION. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

rmsharp and others added 7 commits June 21, 2026 02:01

rmsharp mentioned this pull request Jun 21, 2026

docs: generalize the reasoning-tier recommendation into a cross-cutting convention #39

Merged

rmsharp merged commit 4bba477 into KJ5HST:main Jun 22, 2026

rmsharp added a commit to rmsharp/methodology that referenced this pull request Jun 22, 2026

Merge upstream/main: land v2.9 release (KJ5HST#38 tutorials + KJ5HST#39…

d2ac7e7

… reasoning-tier)

rmsharp deleted the feat/tutorials-p1-scaffolding branch June 22, 2026 18:42

rmsharp mentioned this pull request Jun 22, 2026

docs(tutorials): complete the hands-on tutorial roadmap (T3, T4, T6, T7, T8) #40

Merged

Navigation Menu

Repository navigation

docs(tutorials): hands-on learning track — core trio T1/T2/T5 + sample project - #38

docs(tutorials): hands-on learning track — core trio T1/T2/T5 + sample project#38
rmsharp merged 7 commits into
KJ5HST:mainfrom
rmsharp:feat/tutorials-p1-scaffolding

rmsharp commented Jun 21, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

rmsharp commented Jun 21, 2026

What this adds

Design principles (held throughout)

Verification

Notes for the maintainer

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant