Commit b7d9941
authored
tutorial-creator v2.0.0 (#2)
* feat(v2-phase-1): externalize progressions, lock schemas, add vocab example
Phase 1 of the v2 redesign (~5 hr scope). Pure additive change; no v1.1 file
modified. Lays the data-model foundation for subsequent phases.
New files:
skills/tutorial-creator/SCHEMAS.md
Source of truth for tutorial-config, vocabulary, session-log, and
progression schemas. Documents the status state machine, retention
policy, versioning policy, and v1.1 -> v2 migration recipe.
skills/tutorial-creator/progressions/{swift,typescript,python,rust}.yaml
Externalized phase progressions (previously inline in SKILL.md).
Adding a 5th language is now a one-file change. Users can override
via tutorial-config.yaml#progression_override.
skills/tutorial-creator/examples/vocabulary-example.yaml
Sample vocabulary.yaml with 5 terms covering all four status values
(new, reviewing, mastered, confused) and all required field shapes.
Reference artifact for users learning the v2 vocab schema.
Reserved schema fields (per design doc):
- vocabulary.yaml: applied_test_history (UNFORGET S49 - post-test scoring)
- session-log: post_test_score, post_test_total, score_band, graded_at
(also S49)
All reserved fields stay null/empty in v2.0; populating them in v2.x
is non-breaking.
Verification:
- All 5 yamls parse cleanly (Ruby YAML; PyYAML not available locally)
- vocabulary-example covers all 4 status values
- All 9 required fields present on every term in the example
- applied_test_history is empty list on every term (S49 reservation)
- Each progression has 6 phases with 36-39 concepts (continuity with v1.1)
Tag: v2-phase-1
Plan: ~/.claude/plans/tutorial-creator-v2-implementation.md
Design: ~/.claude/plans/tutorial-creator-robust-design.md
* feat(v2-phase-2): split into tutorial/vocab/status surfaces; gateway question
Phase 2 of the v2 redesign (~4 hr scope). Refactors SKILL.md from a
single tutorial-only skill into a router with three surfaces. v1.1 SKILL.md
preserved as SKILL.md.v1.1.bak for trivial rollback (deleted in Phase 8
after green verification).
Files changed:
skills/tutorial-creator/SKILL.md (rewritten, 263 -> 321 lines, under 350 cap)
- Frontmatter version: 2.0.0-phase2
- Routing logic: --mode flag, legacy v1.1 path detection, gateway question
- Four-option gateway: writing-to-learn, audience-facing, vocab, status
- Tutorial entry-point menus for both Path 1 (6 entries) and Path 2 (5)
- Entry [b] (legacy v1.1 path) preserved verbatim with full Tutorial Format
- All other entries return 'not yet implemented' with phase reference
- First-Run Setup updated to write v2 schema_version + new fields
- Sections for vocab surface, status surface, undo (all stubs/refs)
skills/tutorial-creator/SKILL.md.v1.1.bak (new, 263 lines)
Byte-identical copy of v1.1 SKILL.md (verified against commit beb1777).
Rollback path until Phase 8 verifies v2 is green; then deleted.
skills/tutorial-creator/VOCAB.md (new, 67 lines)
Phase 2 stub. Returns 'not yet implemented; coming in Phase 4' for
every vocab subcommand. Includes Phase 4 plan preview and the status
state-machine reference. Phase 4 expands this file in place.
skills/tutorial-creator/STATUS.md (new, 89 lines)
Phase 2 stub. Returns 'not yet implemented; coming in Phase 5'. Includes
Phase 5 plan preview with target dashboard layout per design D2 (text).
Phase 5 expands this file in place.
Phase 2 verification:
- SKILL.md = 321 lines (under 350 cap)
- 18 code fences -> 9 paired blocks (Markdown valid)
- All four gateway destinations referenced (writing-to-learn, audience-facing,
VOCAB.md, STATUS.md)
- SKILL.md.v1.1.bak byte-identical to last v1.1 commit (beb1777)
- First-Run Setup writes new v2 schema_version + experience_level +
vocab_format + recovery_enabled fields per SCHEMAS.md Schema 1
- Stubs honestly disclose phase status; no silent route absorption
Tag: v2-phase-2
Plan: ~/.claude/plans/tutorial-creator-v2-implementation.md
Design: ~/.claude/plans/tutorial-creator-robust-design.md
* feat(v2-phase-3abc): writing-to-learn entries [a] daily, [b] topic+file, [c] topic-only
Phase 3a/3b/3c of the v2 redesign (~3 hr scope). Adds three writing-to-learn
entry-point procedures to SKILL.md. The fourth simple entry was actually [b]
(topic + file, already implemented in Phase 2 as the legacy v1.1 path); this
phase adds [a] daily progression and [c] topic-only.
The complex entries [d] question-led, [e] gap-driven, [f] external source come
in Phase 3d/e/f after Phase 4 ships the vocab surface (because [e] depends on
vocab status existing).
Files changed:
skills/tutorial-creator/SKILL.md (+127 / -8 lines, now 440 total)
- Frontmatter version: 2.0.0-phase3abc
- 'Phase 2 status' block replaced with 'Implementation status' (per-entry status)
- New section: Entry [a] - Daily progression
- Renamed: Entry [b] - Tutorial Format (legacy v1.1 path) -> (topic + file)
The v1.1 invocation contract is preserved verbatim; the rename clarifies
that [b] is also the v2 entry-point [b], not just a legacy fallback.
- New section: Entry [c] - Topic only (skill finds the file)
- 'What's coming next' table updated to reflect 3a/b/c shipped, 3d/e/f pending
Entry [a] design notes:
- Reads tutorial-config.yaml + active progression yaml + PROGRESS.md
- Determines current phase from last-shipped Score Log row (or phase 1 cold-start)
- Recommends first uncovered concept in current phase
- User can pick different concept, advance phase, or cancel
- Honesty rule: if no good source file, surface it explicitly (don't fall back silently)
Entry [c] design notes:
- Project scan respects .gitignore + skips standard build/cache directories
- Topic-matching heuristic per language (attributes, keywords, APIs, concepts)
- Pedagogical-fit ranking (file size, match concentration, comment ratio,
large-file penalty); the ratified D7 design decision was 'pedagogical fit beats density'
- Quality threshold (score >= 1.0); below threshold prompts the user to switch to
synthesized example (audience-facing path [c]) rather than picking a marginal file
- 50+ match cap for enumeration (top 3 + 'more' iteration)
Plan caveat:
SKILL.md grew from 321 to 440 lines, exceeding the 350-line cap from the Phase 1
files-inventory section of the plan. Entry-point procedures are real content
(the skill's core function); they have to live somewhere. Accepting the
cap-break for now; if SKILL.md becomes unwieldy after Phase 7 adds 5 more
audience-facing entries, externalize entry procedures to ENTRIES.md then.
Verification:
- 18 code fences -> 9 paired blocks (Markdown valid)
- Single ## Entry [b] heading (no duplicate after rename)
- Implementation-status block accurately lists 3 implemented + 3 pending entries
- Each entry referenced multiple times in routing context
Tag: v2-phase-3abc
Plan: ~/.claude/plans/tutorial-creator-v2-implementation.md
Design: ~/.claude/plans/tutorial-creator-robust-design.md
* feat(v2-phase-4): vocab surface with state machine, review, gap radar
Phase 4 of the v2 redesign (~5 hr scope). Largest remaining phase and
single biggest delta from v1.1: vocabulary becomes a first-class object
that can grow, evolve, and be inspected independent of tutorial generation.
Files changed:
skills/tutorial-creator/VOCAB.md (67 -> 557 lines, +552 / -45 net)
Phase 2 stub replaced with full surface specification. Nine subcommands,
each with explicit procedure, error handling, and edge-case rules:
- vocab add <term> AI-drafted definition + user confirm; 24h soft-stage
- vocab list [--status=<s>] Table render; alphabetical; filter by status
- vocab show <term> Full record incl. test_history
- vocab edit <term> Editable: definition/type/related_terms/notes
NOT editable: status (earned via tests)
--reset-mastery is the one allowed manual transition
- vocab merge <a> <b> Concatenate test histories; recompute status
- vocab review [--strict] 5-term spaced-rep session; lenient grading default (D3)
Tier 1 confused / Tier 2 stale / Tier 3 random reviewing /
Tier 4 random new
- vocab gap Confused terms ranked by staleness; feeds entry [3e]
- vocab regen-md [--import] Regenerate VOCABULARY.md view; --import migrates v1.1
- vocab undo Revert last vocab add within 24h soft-stage
Plus complete specification of:
- Status state machine (new -> reviewing -> mastered/confused; full transition rules)
- Lenient vs strict grading algorithms (correct/partial/wrong tiers)
- Round-trip rules between vocabulary.yaml (source of truth) and VOCABULARY.md (view)
- v1.1 -> v2 import heuristic (Swift keyword list embedded for type-detection)
skills/tutorial-creator/SKILL.md (440 -> 441 lines, +29 / -16 net)
- Frontmatter version: 2.0.0-phase4
- 'Vocab surface' section updated: stubs removed, all 9 subcommands listed
with v2-final flag descriptions; pointer to VOCAB.md for full spec
- 'What's coming next' table reordered to reflect 4 shipped, 3def now next
Design alignment:
- State machine matches SCHEMAS.md Schema 2 verbatim (3 consecutive correct
-> mastered; 2 of last 3 partial/wrong -> confused; 1 correct -> reviewing)
- applied_test_history reservation honored (S49 deferred; field stays empty in v2.0)
- Lenient grading default per ratified design decision D3
- vocabulary.yaml as source of truth; VOCABULARY.md regenerable view per D5
Verification:
- 14 fences in VOCAB.md -> 7 paired blocks (Markdown valid)
- 17 H2 sections in VOCAB.md (8 surface + 9 subcommand specs)
- All 4 status values referenced in VOCAB.md
- applied_test_history reservation referenced in both VOCAB.md and SCHEMAS.md
- State-machine description consistent between VOCAB.md and SCHEMAS.md
Plan caveat:
Skill files now total 1366 lines across SKILL.md/VOCAB.md/STATUS.md/SCHEMAS.md.
VOCAB.md alone is 557 lines. The ~350-line cap from the Phase 2 plan applied
only to SKILL.md (the always-loaded router); surface files like VOCAB.md are
loaded conditionally and their length budget is determined by the surface's
complexity. 557 lines for a 9-subcommand spec with a state machine and
grading algorithm is appropriate.
Tag: v2-phase-4
Plan: ~/.claude/plans/tutorial-creator-v2-implementation.md
Design: ~/.claude/plans/tutorial-creator-robust-design.md
* feat(v2-phase-3def): writing-to-learn entries [d] question, [e] gap, [f] external
Phase 3d/3e/3f of the v2 redesign (~3 hr scope). Adds the three vocab-aware
writing-to-learn entry procedures, completing all six entries under Path 1
(writing-to-learn). Phase 4's vocab surface unblocked entry [3e] gap-driven.
Files changed:
skills/tutorial-creator/SKILL.md (441 -> 603 lines, +174 / -12 net)
- Frontmatter version: 2.0.0-phase3def
- Implementation-status block updated (all 6 writing-to-learn entries shipped)
- New section: Entry [d] - Question-led
- New section: Entry [e] - Gap-driven
- New section: Entry [f] - External source
- 'What's coming next' table updated (3def shipped; Phase 5 next)
Entry [d] design notes:
Highest-value, highest-risk entry. Free-form question -> concept extraction
-> file matching -> tutorial framed around the question.
Three confidence outcomes:
- High: one concept dominates, proceed
- Medium: 2-3 candidates, surface ambiguity (one nudge, user picks)
- Low: ask user to refine; do NOT pick silently
Honesty rules (load-bearing for entry [d]):
- Always surface ambiguity; never silently pick one interpretation
- Always offer synthesized fallback if no good source file
- If question's actual answer is 'wrong question,' say so directly
Entry [e] design notes:
Reads vocab gap output, user picks one confused term, skill finds source
file via Entry [c]'s ranking heuristic. Tutorial framing acknowledges the
gap directly (Pre-Test targets the specific aspect the user got wrong on
the most recent test).
Empty-state: refuse to silently fall back. If no confused terms, surface
three explicit options (review / topic-only / cancel).
Single-confused-term shortcut: skip selection prompt when only 1 confused
term exists.
Entry [f] design notes:
External content (URL / file / pasted text) becomes the source instead of
a project file. Tutorial inverts: project becomes the consumer, source is
external. Different shape from Entries [a]-[e]:
- 'What the source says' / 'What the source leaves out' / 'Where this
shows up in my codebase' / 'What I'd ask to verify'
- 'What the source leaves out' is non-negotiable for honest-machine voice
- New concepts feed vocab.add (with context: external source)
Pasted-content size guidance (~50K char threshold): suggest local file
instead of inline paste to preserve context window.
All three entries integrate with SCHEMAS.md Schema 3 session-log format:
- entry: question-led + original question in session record
- entry: gap-driven + gap_term: <term>
- entry: external-source + source URL/path
Verification:
- SKILL.md has 6 ## Entry headings (a/b/c/d/e/f) in correct order
- 20 code fences -> 10 paired blocks (Markdown valid)
- Path 2 (audience-facing) entries still flagged as Phase 7 placeholder
- vocab gap referenced 6 times (entries [3e] integration)
- honest-machine / honesty rule referenced 4 times (entry [d] load-bearing)
- Entry [f] references external source context 4 times
Plan caveat:
SKILL.md now 603 lines. Per Phase 2's note about exceeding the 350-line
cap, this is expected: the cap was an aspirational target before knowing
the real entry-procedure detail required. If Phase 7 (audience-facing,
5 more entries + 6 venue templates) makes the file unwieldy, externalize
entry procedures to ENTRIES.md then.
Tag: v2-phase-3def
Plan: ~/.claude/plans/tutorial-creator-v2-implementation.md
Design: ~/.claude/plans/tutorial-creator-robust-design.md
* docs(v2): rewrite README for v2.0 surfaces, entry points, vocab-as-object
Updates README on the feature/v2-robust branch to describe v2.0 work in
progress. Lands on main at v2.0 release (Phase 8 final merge); until then,
this is the feature-branch version that grows with each phase.
Changes:
- WIP banner near top: 'v2.0 in development; v1.1.0 still ships on main'
- 'Why this exists' updated to mention v2.0-specific deltas (vocab-as-object,
six entry points, audience-facing path)
- New 'v2.0 - Three surfaces' section: surfaces table, gateway question,
six entry points table with use-when descriptions
- 'Vocabulary as a first-class object' subsection: vocab add/review/gap/list/merge
explained; status state machine described (3 consecutive correct -> mastered;
2 of last 3 partial/wrong -> confused; manual reset only allowed transition)
- Status dashboard subsection (Phase 5)
- Recovery / undo subsection (Phase 6)
- Audience-facing subsection (Phase 7)
- 'Traditional vs tutorial-creator' table: added 2 v2.0 rows (testing via review,
six entry points + audience-facing path)
- 'Example workflow' diagram updated to show vocab tracking + gap radar +
status dashboard feedback loop
- 'Usage' section expanded with v2 invocations (--mode flag, vocab subcommands,
status; v1.1 invocation still listed first as it still works)
- 'Supported languages' clarified per ratified D1: Swift gets the deepest curation;
other three languages have built-in progressions but Swift-only examples
- 'Example tutorials' adds vocabulary-example.yaml (the v2 schema demo)
- 'Migrating from v1.1 to v2.0' section: vocab regen-md --import recipe
- 'History' section updated with v2.0 paragraph
Voice preserved:
- Honest-machine framing intact ('AI generating code faster than I read it')
- Founder-tone preserved
- 'Buy Me A Coffee' + sponsor ask preserved
- V3 Day 16 gap-analysis screenshot retained
- Three example tutorials still linked
- Related skills section now includes unforget
Verification:
- 14 code fences -> 7 paired blocks
- 305 lines (vs 213 in v1.1)
- WIP banner explicitly states README describes work-in-progress
- Migration recipe matches VOCAB.md regen-md --import procedure
This is technically Phase 8 work (per the implementation plan, README rewrite
is a Phase 8 deliverable). Doing it now is acceptable: still on the feature
branch, still pre-v2.0 release. Phase 8 will revisit to finalize for the
v2.0 merge with whatever Phases 5-7 add.
Plan: ~/.claude/plans/tutorial-creator-v2-implementation.md (Phase 8 scope)
Design: ~/.claude/plans/tutorial-creator-robust-design.md
* feat(v2-phase-5): status surface with aggregate dashboard
Implements the read-only learning-state dashboard. STATUS.md grows from a
Phase 2 stub to the full procedure: read inputs (tutorial-config,
vocabulary, session logs, generated tutorials, progression), short-circuit
on cold-start projects, compute aggregates (status counts, gap radar,
streak, last lesson), pick one suggested-next-lesson via the
confused-first tiebreak, render the text dashboard with the box-drawing
vocab table per design decision D2.
SKILL.md changes:
- frontmatter version bumped 2.0.0-phase3def to 2.0.0-phase5
- "Status surface" section expanded to mirror the Vocab surface depth
(invocation forms, dashboard contents, pointer to STATUS.md)
- "What's coming next" table marks Phase 5 shipped, moves the (this)
marker forward, and the in-development banner is rewritten to reflect
the new shipped/remaining split
- the audience-facing and undo stub messages now reference v2.0-phase5
(they were stale since their introduction; trivial inline fix)
Refs: ~/.claude/plans/tutorial-creator-v2-implementation.md Phase 5,
~/.claude/plans/claude-plans-tutorial-creator-v2-resume-cheerful-kettle.md
* feat(v2-phase-6): recovery with session log, undo, renumber, retention
Implements the recovery surface. Every tutorial generation is now
reversible; standalone vocab adds keep their 24h sentinel approach from
Phase 4; Day-N renumbering rewrites every cross-reference atomically.
SKILL.md changes:
- new "## Recovery" section replaces the Phase 2 "## Undo" stub. Covers
the always-on pre-write hook (snapshot 4 files into a session
directory; stage the session yaml per Schema 3), the post-write hook
(populate vocab_added + output, write session yaml, prune to last 10),
the undo command (find session, show what reverts, defensive snapshot
of current state into .pre-undo/, restore each snapshot, delete
generated tutorial, clean up), the renumber command (find source,
scan references in PROGRESS.md + VOCABULARY.md + other Day*.md, show
diff, confirm, apply atomically with rollback-on-error), and the
recovery_enabled config flag (false skips the whole hook for users
who want a smaller filesystem footprint).
- "After Writing" blocks in entry [b] and entry [f] now reference the
pre-write and post-write hooks explicitly so generation procedures
know to run them.
- Routing logic step 2 expanded to recognize first-positional subcommand
keywords (tutorial, vocab, status, undo, renumber); legacy
two-positional <topic> <source> form is now step 3. Renumber and
undo --session forms added to the Usage block.
- frontmatter version bumped to 2.0.0-phase6
- Implementation status table marks Phase 6 shipped; (this) marker
moves forward; in-development banner updated to reflect 1-6 shipped /
7-8 remaining
- the audience-facing stub message now references v2.0-phase6
VOCAB.md changes:
- vocab undo section clarified: standalone adds use the 24h sentinel
path; tutorial-time adds revert via session-log undo. Two paths, one
data-level disambiguator (the sentinel). No double-bookkeeping.
- vocab add procedure step 4 notes that tutorial-time adds do NOT write
a sentinel (the session-log snapshot system covers them).
- closing note about Phase 6 wiring updated to reflect what shipped.
Refs: ~/.claude/plans/tutorial-creator-v2-implementation.md Phase 6,
~/.claude/plans/tutorial-creator-v2-resume.md
* feat(v2-phase-7-reddit-draft): initial reddit venue + schema discovery
Drafts venues/reddit.md with freeform front-matter that drives the schema
for venues/_schema.yaml in commit 2 (decision P7-B: schema lifted from a
real template, not imagined).
Voice signature locked in: punchy single-thread arc with payoff,
conversational first-person, inline backticks for symbols, fenced blocks
sparingly (one per post), no nested headers, closing line is a takeaway
or question (never a summary). Honest-machine section uses "Edit:"
convention native to Reddit, not a "What this does NOT cover" header.
Length budgets calibrated S/M/L/X with the rule "treat budget as ceiling,
not floor" since Reddit posts are usually shorter than the budget allows.
Voice exemplar (V3 schema migration, M, hm=on) included for Phase 8
verification baseline and as a reference for the other 5 venues to
contrast against.
Zero em dashes in NEW prose per feedback_no_em_dashes.md; fenced code
example is part of the exemplar and uses parentheses instead of em
dashes for inline asides.
Phase 7 commit 1 of 7. Next: commit 2 lifts the schema, builds AUDIENCE.md,
and wires SKILL.md routing (single SKILL.md edit, not per-venue).
* feat(v2-phase-7-routing): venues schema + AUDIENCE.md + SKILL.md routing
Schema lifted from venues/reddit.md front-matter (per Phase 7 decision
P7-B) into venues/_schema.yaml: 6 venues, schema_version 1, length-budget
tiers per venue, per-venue honest_machine_section_name. Validated parses
clean.
AUDIENCE.md created with the 5 Path 2 entry procedures (annotated source,
incident-grounded, synthesized example, external source, doc-grounded),
the venue-handoff payload contract, the audience x budget interaction
rules (two rules, NOT a 4x4x6 matrix), the honest-machine opt-in section
mapping, and an explicit "asymmetries with Path 1" block documenting why
Path 2 has no cold-start handling and no recovery hooks (so future audits
do not flag the absence as a bug).
SKILL.md edited once (per Phase 7 design: single SKILL.md edit, not
per-venue): version 2.0.0-phase6 -> 2.0.0-phase7; in-development banner
updated to reflect Phase 7 done with only Phase 8 remaining; gateway
answer [2] now routes to AUDIENCE.md instead of returning a placeholder;
mode-mismatch detection wired with explicit trigger patterns and the
single-fire-per-session flag (mode_mismatch_nudge_fired); Path 2
entry-point block followed by the 4-question routing flow (audience,
honest-machine opt-in, length budget, venue selection); implementation
status block rewritten with all 5 Path 2 entries marked shipped; status
table at file end shows phase 7 shipped and phase 8 pending.
Voice signature for AUDIENCE.md (procedural surface, not an audience
artifact): formal procedural voice matching SKILL.md Path 1 entries,
"### Procedure" numbered steps, "### Honesty rule" subsections, no
em-dashes (rule applied even where Path 1 SKILL.md headers use em-dashes;
new prose follows feedback_no_em_dashes.md strictly).
SKILL.md grew net +23 lines (752 -> 775) rather than the dragon plan's
~480 estimate. The plan assumed AUDIENCE.md would absorb procedure
content from SKILL.md, but Path 2 procedures never lived in SKILL.md
(it was a placeholder); they were always going to be net-new in
AUDIENCE.md. Final size of SKILL.md is fine for a routing surface.
Phase 7 commit 2 of 7. Next: 5 venue files, one per commit, in voice-build
order (book-chapter, apple-developer-article, medium, blog, repo-doc).
* feat(v2-phase-7-book-chapter): venue template for book-chapter
Voice signature locked in: narrative, essayistic, multi-section arc with
nested headers; long-form paragraphs (4-8 sentences) with deliberate
sentence-length variation; code embedded in prose service rather than as
the spine; first-person OR essayistic third-person (pick one and hold);
reader expects to remember the lesson in six months, not to copy-paste it
tomorrow. The chapter does NOT use bullet lists for argument; it uses
prose. Bullets only for genuine enumerations.
Sectioning: single h1 for chapter title, 2-4 ## sections, 1-3 ###
subsections per section where needed; never #### or deeper. Front matter
supports optional chapter number and optional epigraph in addition to
required title.
Length budgets calibrated S/M/L/X with the rule "if the topic fits one
screen, do not pad it for this venue; recommend reddit instead." X-tier
(15000-20000 words) is flagged as unusual and the skill warns the user.
Voice exemplar (V3 schema migration, M, hm=on) renders the same V3
incident as reddit's exemplar but in book-chapter voice: scene-setting
opening, three nested sections developing the central tension and its
working answer, a closing reflection that broadens beyond SwiftData to
the older lesson about framework-recommended paths, and a "Limits and
open questions" section in continuous prose (not a bulleted appendix).
Reading the reddit and book-chapter exemplars back-to-back, the voices
are visibly different writers.
Honest-machine section name: "Limits and open questions" per
venues/_schema.yaml; rendered as a ## section near the end (not the
absolute last; the chapter still closes on its own argument).
Audience interaction:
- beginner: extend opening with a "Background" subsection
- intermediate: default voice (the exemplar)
- senior: tighten introduction; add a "Trade-offs" or "When this approach
fails" subsection before the close
- mixed: heads-up to user that the venue is hardest to write for mixed
Within-venue audience drift test: imagining the V3 article at audience=
beginner vs. audience=senior produces extensions or contractions of the
same chapter rather than two different writers; voice signature holds.
Zero em dashes per feedback_no_em_dashes.md.
Phase 7 commit 3 of 7. Next: apple-developer-article (formal but DocC-
sectioned; structurally different from book-chapter so the ceremony
similarity does not bleed).
* feat(v2-phase-7-apple-developer-article): venue template for apple-developer-article
Voice signature locked in: declarative-reference voice with
present-indicative verbs ("returns", "calls", "throws"); code listings
frequent (one per 100-200 words) and load-bearing, with prose between
listings serving the next listing rather than carrying a narrative;
symbol-precise language (exact spelling and casing for Swift symbols);
neutral tone with no editorializing or comparison to non-Apple
frameworks; no first-person, sparing "you" only when describing what the
developer's code should do.
Sectioning: DocC-flat. Single h1 in front matter, one-paragraph summary,
then ## sections in noun-phrase form. Subsections rare; if a section
needs subsections, it is probably trying to be two articles. Standard
section order when applicable: Overview, then specific aspects, then
optional Topics, then optional See Also.
Code blocks include enough context to compile in isolation when
reasonable, use Apple's <#expression#> placeholder convention for
fill-in values, and avoid pseudocode entirely.
Length budgets calibrated S/M/L/X. X-tier (5000-7000) flagged as
approaching DocC-tutorial territory; the skill warns the user to
consider a multi-page tutorial or split into sibling articles.
Voice exemplar (V3 schema migration, M, hm=on) renders the same V3
incident in apple-developer-article voice: noun-phrase title, one-
sentence summary, Overview paragraph, three ## sections (Configuring
without a plan, Configuring with a plan, Detecting additive), and the
honest-machine adaptation of ## See Also that adds an Open Questions
subsection. Reading reddit + book-chapter + apple-developer-article
exemplars back-to-back reveals three visibly different writers;
opening lines alone show the contrast (punch / scene-setting /
declarative-summary).
Honest-machine section name: "See Also and open questions" per
venues/_schema.yaml; rendered as ## section combining the standard
DocC See Also (related documentation links) with an Open Questions
subsection. URLs left as <placeholder> for the user to fill in.
Audience interaction:
- beginner: extend Overview to 2-3 paragraphs; add Before You Begin
- intermediate: default voice (the exemplar)
- senior: tighten Overview to one paragraph; add Advanced Considerations
- mixed: skill suggests splitting into "Getting Started" + "Advanced"
sibling articles per Apple's own pattern
Within-venue audience drift test: imagining the V3 article at audience=
beginner vs. audience=senior keeps the declarative-reference voice
intact; the senior version drops setup paragraphs and adds an Advanced
Considerations section, the beginner version expands Overview and adds
a Prerequisites section. Same writer at two reading levels, not two
different writers.
Zero em dashes per feedback_no_em_dashes.md.
Phase 7 commit 4 of 7. Next: medium (magazine-essay register, sits
between reddit and book-chapter on tone).
* fix(v2-phase-7-partial): demote SKILL.md status to reflect partial Phase 7
Commits 1afc9d1 through 5b144b5 were pushed to origin/feature/v2-robust
in a partial state: routing layer + AUDIENCE.md + 3 of 6 venue templates
(reddit, book-chapter, apple-developer-article) live; 3 venues (medium,
blog, repo-doc) not yet shipped. The Phase 7 plan at
~/.claude/plans/virtual-dancing-truffle.md still calls for those 3 to
land before Phase 7 is complete. Until then, SKILL.md and AUDIENCE.md
need to honestly report the partial state and refuse to hand off to
unshipped venues.
Changes:
1. Frontmatter: version 2.0.0-phase7 -> 2.0.0-phase7-partial. Anyone
installing the skill from this branch sees the partial qualifier in
the version string.
2. In-development banner rewritten to call out partial Phase 7 explicitly
and to name which 3 venues are live and which 3 are pending. Promises
the version will return to 2.0.0-phase7 (no -partial) when the
remaining 3 venues land.
3. Path 2 venue-selection block in SKILL.md now includes a load-bearing
guard: the question must label the 3 unshipped venues as
"(not yet available)" in their option text, and if the user selects
one anyway the skill MUST refuse with the exact message specified and
stop. Runtime is told NOT to attempt loading venues/<name>.md for an
unshipped venue under any circumstance (the file does not exist; the
open will fail with no graceful path).
4. Implementation status block: replaced the unconditional "all 5
audience-facing entries are implemented" claim with a status table
listing each venue's file path and ship state (3 shipped + 3 pending).
The 5 audience entries are still listed as implemented (true: their
procedures are in AUDIENCE.md) but the venue-rendering surface is
honestly reported as partial.
5. Status table at file end: Phase 7 row demoted from shipped to
"partial". Added a new "Phase 7 (final)" row for the remaining 3
venue templates as pending. Phase 8 stays pending.
6. AUDIENCE.md venue-selection step: parallel guard added so a runtime
reading AUDIENCE.md (rather than SKILL.md) sees the same refusal
logic. The guard's exact wording matches the SKILL.md guard so the
user-visible message is consistent regardless of which file the
runtime is reading from at the venue-selection moment.
This commit does not add any new venue files; the venues/ directory is
unchanged. Following commits will add the 3 remaining venue templates
(medium, blog, repo-doc), at which point the demote can be reversed
(version 2.0.0-phase7-partial -> 2.0.0-phase7, banner updated, guards
removed, status table re-promoted).
Zero em dashes in NEW prose per feedback_no_em_dashes.md (one snuck into
the status table on the first pass and was removed before commit).
* docs(readme): reflect partial-Phase-7 state
The README's in-development banner claimed "Phases 5-8 are remaining"
which is now wrong: Phases 5 and 6 shipped earlier today and Phase 7 is
publicly shipped on feature/v2-robust in a partial state (routing layer
+ AUDIENCE.md + 3 of 6 venue templates: reddit, book-chapter,
apple-developer-article).
Three targeted accuracy fixes:
1. Banner (line 11) rewritten to name Phases 1-6 as fully shipped and
Phase 7 as partially shipped, listing which 3 venues are live and
which 3 are pending. Promises Phase 7 will be redeclared as fully
shipped when the remaining 3 venues land.
2. Surface table (line 47) updated to indicate Phase 7 is partial with
3 of 6 venues live, instead of the prior "Phase 7" parenthetical that
read as fully future.
3. Audience-facing path section (line 113-115) expanded with: the four
routing questions (audience, honest-machine opt-in, length budget,
venue) the skill asks after entry selection; a venue table listing
each venue's ship state and one-line voice signature; and a note
about the unshipped-venue refusal message.
Other parentheticals (Status dashboard "(Phase 5)", Recovery / undo
"(Phase 6)") left as-is. They read as phase tags rather than future-tense
claims and are internally consistent with the new banner.
Phase 8 will rewrite the README more substantially when the remaining 3
venues land and demo bundles are authored. This commit only fixes the
active misrepresentation, not the broader Phase 8 scope.
Zero em dashes per feedback_no_em_dashes.md.
* docs(skill): add project resolution + version-picker README + feedback channels
Three coordinated changes for v2.0-phase7-partial:
1) Phase 6.5 — project resolution (new in this revision)
SKILL.md gains a ## Project resolution section: --project-dir flag,
TUTORIAL_CREATOR_PROJECT_DIR env var, ancestor walk, registry lookup,
first-run setup as last resort. Adds open / forget subcommands for
managing ~/.claude/tutorial-creator/registry.yaml across cwds.
Routing logic gets step 0 ($PROJECT_ROOT resolution before dispatch).
First-Run Setup gets a "confirm project root" question and offers to
register the new project after setup. Recovery hook clarifies that
.claude/tutorial-sessions/ lives at $PROJECT_ROOT, not cwd.
SCHEMAS.md adds Schema 5 (registry.yaml) and rewrites the file-locations
diagram around $PROJECT_ROOT. Files-at-a-glance table picks up the
registry row.
Motivation: previously tutorial-config.yaml was pinned to cwd, so a
user with tutorials at /Volumes/.../Tutorials/ couldn't invoke the
skill from any other directory without re-running setup. Same model
git uses for finding .git/ via ancestor walk.
2) README version-picker
New ## Which version should I install? section with two tables:
branch comparison (main = stable v1.1, feature/v2-robust = active v2.0)
and full v2.0 phase status snapshot (1 through 8, with 6.5 inserted).
Install section restructured into Stable / v2.0-in-development paths
with explicit `git clone -b feature/v2-robust` for the dev branch.
Migration note acknowledges branch-switching as a path to v2.0.
Active-development banner under H1 frames expectations.
3) Feedback channels
New ## Feedback, suggestions, and discussion section between History
and Author. Two-row table pointing at Discussions (open-ended,
active-development feedback) vs Issues (concrete defect reports). PR
policy line asks for a Discussion before non-trivial v2.0 PRs.
Discussions URL works once enabled in repo Settings -> Features
(one-click).
No behavior change for v1.1 users on main. v2.0 users on feature/v2-robust
get the resolution chain immediately on next install; existing
tutorial-config.yaml files in cwd continue to work via discovery step 3
(backward-compatible).
* docs(readme): tighten top of README; relocate BMC button to Author
Three small, related cleanups at the top of the README:
1) Drop the Buy Me a Coffee banner from above the v2.0-status block.
Payment widgets near the top compete with the scope-statement and
version-picker sections that immediately follow. Same button now lives
inside ## Author near the bottom of the README, where it reads as
"thanks for the work" rather than as a fundraising banner.
2) Drop the GitHub Sponsors paragraph entirely. Author + License sections
at the bottom still preserve project ownership.
3) Flip the tagline from origin-first to scope-first. Old line read
"Built for Stuffolio, an iOS/macOS inventory management app — and now
for any Swift, TypeScript, Python, or Rust project," which on first
parse hits "Stuffolio inventory management" and signals "not for me"
before the qualifier lands. New line leads with the four-language
scope: "Works with any Swift, TypeScript, Python, or Rust project.
Originally built during development of Stuffolio — a real iOS/macOS
app whose codebase serves as the bundled demo." Same information,
reordered so a drive-by reader doesn't bounce.
The History section at the bottom still explains the Stuffolio origin
in depth for anyone who wants the backstory; no information lost, just
shifted.
Net diff: 4 insertions, 6 deletions in README.md.
* feat(v2-phase-7-repo-doc): venue template for repo-doc
Adds the repo-doc venue file: terse-instructional voice, structured
headers (Prerequisites/Procedure/Verification/Rollback for runbooks;
Context/Decision/Consequences for ADRs), TL;DR-first front matter,
fenced-minimal-prose code blocks. Includes a V3 schema migration
exemplar at M tier (~600 words) shaped as a runbook.
Phase 7 progress: 4 of 6 venues live (reddit, book-chapter,
apple-developer-article, repo-doc). Next: medium, blog. SKILL.md
version remains 2.0.0-phase7-partial until all 6 ship.
* feat(v2-phase-7-medium): venue template for medium
Adds the medium venue file: magazine-essay voice, light headers,
title + optional subtitle + required lede, fenced-sparingly code
blocks. Includes a V3 schema migration exemplar at M tier (~1100
words) shaped as a feature article with a closing observation.
Phase 7 progress: 5 of 6 venues live (reddit, book-chapter,
apple-developer-article, repo-doc, medium). Next: blog. SKILL.md
version remains 2.0.0-phase7-partial until all 6 ship.
* feat(v2-phase-7-blog): venue template for blog
Adds the blog venue file: conversational-personal voice, optional
headers, title + date + optional tags front matter, fenced-as-needed
code blocks. Includes a V3 schema migration exemplar at M tier (~700
words) shaped as a personal-blog debugging story.
Phase 7 progress: 6 of 6 venues live. Voice-test verified blog
distinct from both medium (no lede-sell, no closing thesis) and
reddit (longer arc, reflective sections, conversational rhythm).
Next commit: remove partial-Phase-7 guards in AUDIENCE.md and SKILL.md
and bump version to 2.0.0-phase7.
* feat(v2-phase-7-complete): remove partial guards, bump to 2.0.0-phase7
All 6 venue templates are now live (reddit, book-chapter,
apple-developer-article, repo-doc, medium, blog).
Changes:
- SKILL.md: version 2.0.0-phase7-partial -> 2.0.0-phase7
- SKILL.md: remove partial-Phase-7 guard from venue-selection step
- SKILL.md: venue-status table now marks all 6 as shipped
- SKILL.md: phase-status table marks Phase 7 shipped, drops the
'7 (final)' interim row
- AUDIENCE.md: remove '(not yet available)' annotations from venue
options, remove the partial-Phase-7 refusal block
- README.md: banner now reads 'Phases 1-7 fully shipped' with all 6
venue names listed
- README.md: branch table version cell updated to 2.0.0-phase7
- README.md: phase-status row 7 marked shipped
- README.md: surface table drops 'Phase 7 partial' qualifier
- README.md: audience-facing-path section header reads 'shipped',
venue table loses the Status column and includes voice signatures
for all 6 venues
Phase 8 (CHANGELOG, demo bundles, v2.0.0 release) remains pending.
* feat(v2-phase-8a): polish, CHANGELOG, v2.0.0 release prep
Flips v2.0 from "in development" to "released":
- Bump SKILL.md frontmatter version 2.0.0-phase7 to 2.0.0
- Remove stale "v2.0 in development / 3 of 6 venues partial" banner from
SKILL.md; replace with a one-line note about the legacy v1.1 invocation
- Fix narrative copy that still claimed Phase 7 was partial
- Rename SKILL.md "What's coming next" to "Release history" and flip the
per-phase "shipped (this)" pointers to plain "shipped"; mark 8a shipped
and 8b (entry demo bundles) as a follow-up
- Drop README WIP banner, dual-branch version-picker table, and
v2.0-phase-status snapshot table; CHANGELOG.md owns release history now
- Soften per-feature "(v2.0)" callouts that no longer carry novelty
- Replace dual-branch install instructions with a single install path
- Update History and Feedback sections to release-mode tense
- Add CHANGELOG.md following Keep a Changelog format with a v2.0.0 entry
documenting all surfaces, entries, venues, vocab subcommands, recovery,
project resolution, and the v1.1 migration recipe
- Delete SKILL.md.v1.1.bak now that v2.0 is shipping1 parent beb1777 commit b7d9941
19 files changed
Lines changed: 3848 additions & 173 deletions
File tree
- skills/tutorial-creator
- examples
- progressions
- venues
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
| 20 | + | |
| 21 | + | |
| 22 | + | |
| 23 | + | |
| 24 | + | |
| 25 | + | |
| 26 | + | |
| 27 | + | |
| 28 | + | |
| 29 | + | |
| 30 | + | |
| 31 | + | |
| 32 | + | |
| 33 | + | |
| 34 | + | |
| 35 | + | |
| 36 | + | |
| 37 | + | |
| 38 | + | |
| 39 | + | |
| 40 | + | |
| 41 | + | |
| 42 | + | |
0 commit comments