agents/presentation-learning-journey: record rebuild protocol and data-loss prevention rule

Added mandatory learning: never run destructive git ops (checkout --, restore,
reset --hard) on uncommitted work. Added commit-per-milestone protocol, Write-tool
vs sed preference for large restructures, and full rebuild summary for the
2026-04-18 weather-reporter 37-slide deck.

Co-Authored-By: Claude <noreply@anthropic.com>

.claude/agents/presentation-learning-journey.md

@@ -120,7 +120,25 @@ _Findings from previous executions are recorded here. Add new entries as bullet
 - **2026-04-17 slides dropped during the flatten** (12 total): old slides 19 (Day 1 "Putting It All Together" section divider — bug: had no `data-level`), 20 (Four Layers summary), 21 (Day 1 Complete title slide), 22 (Memory section divider — folded into CLAUDE.md), 23 (CLAUDE.md "Your Project's Brain" — duplicated slide 7 content), 26 (Building section divider), 27 (Creating Your First Skill — replaced by new slide 23 how-to), 29 (Creating Your First Agent — duplicate of slide 14/17), 31 (Agents vs. Skills — Where They Live, niche), 32 (How to Use Your Agent, niche), 33 (Commands & Orchestration section divider), 37 (Day 2 Summary). Surviving Day-2 content was redistributed: "What Goes in CLAUDE.md" + "How Memory Loads" → CLAUDE.md section, "Skill Config Fields" → Skills section, "Agent Config Fields" → Agents section, "Commands — Entry Point" → Commands section, "Command → Agent → Skill" + "Two Skill Patterns" → Workflow section. **Heuristic worth recording**: when flattening sections, audit for orphan section dividers without `data-level` (those are silent bugs — no fill renders) and for content slides whose intro analogy is duplicated by an earlier section's intro (those waste a slide and confuse the reader).
 - **2026-04-17 fixes from user review of the flatten** (two misses worth recording): (1) **`/context` command was missing.** I had only included `/clear` and `/compact` on slide 6 (the Context how-to). The user pointed out `/context` is the *diagnostic* command — it shows current token usage and a breakdown by source (system / tools / files / conversation). Fix: retitled slide 6 from "How to Reset Your Context" → "How to Manage Your Context", restructured the 3 hiring-steps as Check (`/context`) → Trim/Reset (`/compact` or `/clear`) → Start fresh, expanded the analogy-box to cover all three commands, and updated slide 26's commands inventory from "four built-in commands" to "five" (added a 🧠 `/context` use-case-item between `/agents` and `/clear` & `/compact`). **Rule**: when authoring a "how to manage X" slide, list the *diagnostic* command first, *modifier* commands second — users always want to inspect before they mutate. (2) **Context-window diagram was lost.** The original deck had `<img src="../assets/context-window.jpeg" />` on the dropped slide 23 (CLAUDE.md "Your Project's Brain"), and I dropped the image with the slide. The image is actually about the *context window* (token-budget breakdown), not CLAUDE.md, so it was always misplaced — but I should have caught it during the redistribute pass. Fix: inserted it into slide 4 ("Claude's Brain") right after the analogy-box, before the "Everything you give Claude…" use-cases list, where it visually anchors the brain metaphor. **Rule**: when dropping a slide, scan its body for `<img>` tags and explicitly decide whether each image belongs in the new structure — they're easy to lose because they don't trigger any of the structural-integrity checks (data-slide, data-level, goToSlide).
 - **2026-04-17 added "What Loads at Session Start" slide (now slide 5, total slide count 32 → 33)**: new content slide between the brain-inventory (slide 4) and the Thariq tip (now slide 6) covering progressive disclosure for skills, agents, and MCPs. Uses `presentation/assets/context.jpg` (a separate diagram from `context-window.jpeg`, which is the token-budget visual on slide 4). Authoritative source for the loading semantics is `reports/claude-skills-for-larger-mono-repos.md`: skill *descriptions* are loaded into context up to a 15K-character budget at startup; full content is fetched on-demand when the skill is invoked. Subagents follow the same description-vs-full-content pattern. MCPs default to loading full tool definitions upfront (~1.5K tokens each per `reports/claude-advanced-tool-use.md`), but can be marked `defer_loading: true` for on-demand discovery via the Tool Search Tool — I phrased this as "MCPs — on-demand (when configured)" so the slide doesn't overstate the default behavior. The slide ends with two boxes: a `.trigger-box` "One-Liner" recap and an `.info-box` "Why It Matters" that references `/context`. **Rule worth recording**: when describing MCP loading semantics for a non-technical audience, qualify with "when configured" — saying "MCPs are on-demand" without that caveat is technically wrong (the default is upfront).
-- **2026-04-17 cross-slide renumber pattern (sed-driven)**: inserting one slide into Topic 1 (Context) required renumbering 28 `data-slide` attributes (5→6 through 32→33) plus 5 `goToSlide(N)` calls in the slide-2 TOC plus 6 `<!-- TOPIC X: ... (Slides A-B) -->` section banners. Approach used: a single `sed -i ''` pipeline with 28 `-e 's/data-slide="N"/data-slide="N+1"/'` expressions in **descending** order (32→33 first, 5→6 last) to avoid collisions, followed by separate single-call `sed` for banner comments and an `Edit` for the TOC block. This is much faster than 28 individual Edits — sed is justified here because each `data-slide="N"` is unique in the file (the JS uses template strings like `${slideNum}`, never literal numbers) so there's no risk of clobbering JS references. Final section-divider positions after this insertion: **Context 3, CLAUDE.md 8, Agents 14, Skills 20, Commands 26, Workflow 29**. Total slide count is now **33**. **Caveat**: don't run sed and Edit in parallel on the same file — sed modifies the file timestamp and any pending Edit calls will fail with "File has been modified since read". Sequence them.
+- **2026-04-17 cross-slide renumber pattern (sed-driven)**: inserting one slide into Topic 1 (Context) required renumbering 28 `data-slide` attributes (5→6 through 32→33) plus 5 `goToSlide(N)` calls in the slide-2 TOC plus 6 `<!-- TOPIC X: ... (Slides A-B) -->` section banners. Approach used: a single `sed -i ''` pipeline with 28 `-e 's/data-slide="N"/data-slide="N+1"/'` expressions in **descending** order (32→33 first, 5→6 last) to avoid collisions, followed by separate single-call `sed` for banner comments and an `Edit` for the TOC block. This is much faster than 28 individual Edits — sed is justified here because each `data-slide="N"` is unique in the file (the JS uses template strings like `${slideNum}`, never literal numbers) so there's no risk of clobbering JS references. Final section-divider positions after that insertion: **Context 3, CLAUDE.md 8, Agents 14, Skills 20, Commands 26, Workflow 29** (total 33) — superseded by the 2026-04-18 split that moved all positions +1 and raised total to 34; see the 2026-04-18 entry below. **Caveat**: don't run sed and Edit in parallel on the same file — sed modifies the file timestamp and any pending Edit calls will fail with "File has been modified since read". Sequence them.
+- **2026-04-18 opening framing: "There is no one correct way of using Claude Code."** Slide 1 subtitle was changed from "From your first conversation to wiring your first workflow" to this framing. A second line below it reads "This journey is one path among many — a way to build intuition, not a rulebook to follow." Any future edits to the intro slide MUST preserve this non-prescriptive stance. The journey illustrates; it does not mandate.
+- **2026-04-18 slide 2 = Boris GIF (standalone), slide 3 = Six Topics TOC (supersedes prior two-col slide-2 entry).** The GIF at `../../!/root/boris-slider.gif` now lives on its own full-width slide with a centred `<figcaption>` (max-width 820px `<figure>`). The TOC is on slide 3 as a standalone slide titled "Six Topics, One Continuous Arc" using the standard `.toc-list` grid (2-column default, no `grid-template-columns: 1fr` override needed). Total slide count is now **34**. Section-divider positions: **Context 4, CLAUDE.md 9, Agents 15, Skills 21, Commands 27, Workflow 30**. TOC `goToSlide` targets: **4, 9, 15, 21, 27, 30**. The journey bar is shown but empty (0% fill) on slides 2 and 3 — this is correct because neither slide has `data-level` and the JS `SLIDE_LEVELS` map will hold null for those indices. The journey bar hides only on slide 1 (`if (slideNum <= 1)`).
+- **2026-04-18 gotcha: sed `3→4` step was omitted from the renumber chain.** When inserting slide 3 (TOC) between old slide 2 and old slide 3, I ran sed in descending order for old 33→34 down to old 4→5, but had no step for old 3→4 (thinking the new slide 3 was already placed). The Context section divider (old slide 3) kept `data-slide="3"` — a silent duplicate. Fix: one targeted `Edit` to change that element from `"3"` to `"4"`. **Rule**: when splitting a slide and inserting a new one at position N, explicitly confirm that the slide that was at position N is now renumbered to N+1 — it will NOT be caught by the descending sed chain if that chain starts at N+1.
+- **2026-04-18 inline slide number comments drift**: after the renumber, 30+ inline `<!-- Slide N: ... -->` comments were off by 1. Fixed with a single sed pipeline mapping each old comment number to the new one. These comments are cosmetic (no functional effect) but are important for navigating the file manually — keep them in sync after every renumber operation.
+- **2026-04-18 three intro slides borrowed from vibe-coding deck (new slides 3-5, total 34 → 37)**: inserted between old slide 2 (Boris GIF) and old slide 3 (TOC, now slide 6). New opening arc: Slide 1 ("no one correct way") → Slide 2 (Boris GIF) → Slide 3 ("From Vibe Coding to Agentic Engineering" before/after file-tree comparison) → Slide 4 ("What is Vibe Coding?" two-col with analogy-box) → Slide 5 ("Good vs Bad Prompts" two-col with trigger-box) → Slide 6 (six-topics TOC) → Topic sections. Vibe-coding deck slides 2, 3, and 12 were the source; content was adapted into learning-journey visual language (`.col-card bad/good`, `.code-block`, `.analogy-box`, `.trigger-box`) — no CSS was copied from the vibe-coding deck. The before/after file-tree on slide 3 was simplified vs. the source (removed hooks/, rules/, .mcp.json, settings.local.json) to keep it readable for a non-technical audience. Slide 12's prompt examples were adapted with shorter code-block lines to fit the `.col-card` width. The new slides have no `data-level`, so the journey bar shows but renders 0% fill (empty track) for slides 3-6 — expected behavior, journey bar is hidden only on slide 1. Section-divider positions after insertion: **Context 7, CLAUDE.md 12, Agents 18, Skills 24, Commands 30, Workflow 33**. TOC `goToSlide` targets: **7, 12, 18, 24, 30, 33**. **Cross-deck borrowing rule**: read the source deck's slide content verbatim, then restyle into target deck's classes — never copy-paste CSS or invent new CSS classes for ported slides.
+- **2026-04-18 slide 6 redesigned as "Meet the Person" — 5-topic vertical TOC with person metaphor**: replaced the old 2-column 6-item `.toc-list` grid with 5 full-width `.toc-item` rows stacked vertically (inline `style="margin-top: 10px; align-items: flex-start;"` overrides on each row — no new CSS classes). Topic dropped from TOC: **Workflow (slide 33)** — still exists in the deck, just not linked. The 5 remaining `goToSlide` targets are **7, 12, 18, 24, 30** in presentation order. Row order on the slide is Agents → Skills → Context → CLAUDE.md → Commands (brainstorm order the user used, not arc order) — the number badges show the arc-order index (3, 4, 1, 2, 5) so the viewer can mentally reconstruct the sequence. Metaphor map: Agents = "The Person" (specialist hired for a role), Skills = "What the Person Knows" (weather-reporter has skills: fetch data, read charts, write a script), Context = "The Person's Brain" (finite space, ~1M tokens; visualised with an inline capacity meter — green→orange→red gradient bar, no new CSS), CLAUDE.md = "The Pocket Rulebook" (small notebook read at start of every job, survives brain-reset overnight), Commands = "The Trigger" (a single word that kicks off a whole sequence). Context row includes an inline capacity-meter div (pure inline CSS, no new classes) with label "~1M tokens capacity". CLAUDE.md metaphor chosen over "employee handbook" because "pocket rulebook" reinforces portability and personalness — consistent with "the person carries it everywhere" vs "the company posts it on the wall". **Speech-to-text artifact pattern**: user said "one million contacts" — this is drift for "one million tokens". Corrected silently in the slide. Future transcription artifacts: watch for "contacts" (tokens), "agents" (sometimes means "skills" in casual speech), "commands" (sometimes means "prompts"). **Workflow section still exists at slide 33** — pending user decision on whether to remove it from the deck entirely or keep it as an unlisted bonus section.
+- **2026-04-18 weather-reporter running-example redesign (slides 7-37 reorder)**: all section content from slide 7 onward was rewritten and reordered around the weather reporter as a single running example. New section order: **Agents (7-12) → Skills (13-18) → Context (19-23) → CLAUDE.md (24-29) → Commands+Workflow (30-37)**. The TOC badges were corrected to show arc-index 1-5 in the new order (was 3,4,1,2,5 brainstorm order). TOC `goToSlide` targets updated to: Agents=7, Skills=13, Context=19, CLAUDE.md=25, Commands=30. LEVELS map heights redistributed to match new arc order: agents=17%, skills=33%, context=50%, claude-md=67%, commands=83%, workflow=100%. Journey ticks reordered top→bottom as: Workflow, Commands, CLAUDE.md, Context, Skills, Agents. The Workflow section divider (slide 33) has `data-level="workflow"` and `section-number` text changed from "Topic 6" to "Putting It All Together" — it's now treated as a subsection inside the Commands+Workflow block, not a standalone topic. Total slide count unchanged at **37**. Both context diagrams preserved: `context-window.jpeg` on slide 20, `context.jpg` on slide 21. Plan document written first at `reports/learning-journey-weather-reporter-redesign.md` before edits.
+- **2026-04-18 plan-first pattern for large redesigns**: for any redesign touching more than 10 slides or reordering sections, write `reports/<name>-redesign.md` first with current→new section map, slide-by-slide outline, asset reuse inventory, and bookkeeping impact table. Proceed with implementation immediately unless a load-bearing ambiguity remains (none in this case). The plan doc also serves as an audit trail for future agents inheriting this presentation.
+- **2026-04-18 LEVELS heights must always track section position in the narrative arc, not any legacy assignment**: when reordering sections, update LEVELS heights AND journey ticks AND data-level attributes together as a unit. Missing any of the three causes the journey bar to jump backward or skip levels, which is confusing for the audience. After reorder: verify by mentally stepping through slides in order and confirming bar height increases monotonically.
+- **2026-04-18 stage-slide vs document-slide principle**: target ≤~25 words of body copy per slide (titles, captions, and code labels don't count). One idea per slide. If a slide makes two points, split or drop the weaker one. The presenter's voice carries the narrative — the slide is a visual anchor only.
+- **2026-04-18 trim defaults**: default to TRIM over SPLIT. When trimming, preserve in priority order: (1) metaphor/analogy taglines — these are what the audience retains, (2) diagrams and images, (3) real repo names and command names (`/weather-orchestrator`, `weather-agent.md`, etc.), (4) code blocks. Drop in priority order: (1) sentences that restate the heading, (2) "In other words…" elaborations, (3) multi-clause run-on descriptions, (4) second `<p>` tags inside `.col-card` elements when the first already captures the idea.
+- **2026-04-18 analogy-box trim pattern**: for analogy boxes with two `<p>` tags, keep only the first (the analogy itself) and fold any factual addendum into the downstream `.trigger-box` or drop it if it duplicates surrounding slide content. Exception: the brain-resets note in slide 20 was folded into the second sentence of the first `<p>` rather than a second `<p>`.
+- **2026-04-18 how-to-trigger intro-sentence removal**: the "The Command" / "The File" green boxes are self-explanatory — the surrounding slide gives context. Drop the `<p>` intro sentence above them (e.g., "You don't write an agent from scratch…") when the box itself already says the same thing. Each removal saves ~15-20 words without losing information.
+- **2026-04-18 warning-box header specificity**: avoid headers like "Two Things Every Non-Engineer Should Know" — they feel condescending and are long. Replace with factual labels ("Two Things to Know") or remove the header entirely if the box content is obvious. The box color (orange) already signals importance.
+- **2026-04-18 CRITICAL DATA-LOSS RULE**: If any tool error (sed failure, Edit collision, file write error) corrupts an uncommitted file, **investigate the root cause and fix it — NEVER run `git checkout --`, `git restore`, `git reset --hard`, or any other destructive git operation on uncommitted work**. The file in the working tree may contain hours of unrecoverable work. Destructive recovery was the cause of the full session loss on 2026-04-18. Always commit after every major milestone (section complete, content verified) so there is always a safe restore point that doesn't require destroying uncommitted edits.
+- **2026-04-18 commit-per-milestone protocol**: for any large rebuild (10+ slides), commit after: (1) opening arc complete, (2) TOC slide complete, (3) each section complete, (4) bookkeeping pass verified, (5) agent Learnings updated. Use `git add <file> && git commit` — never bundle presentation + agent changes into one commit (CLAUDE.md requires separate commits per file). This creates restore points without depending on tool-level error recovery.
+- **2026-04-18 Write-tool full-rewrite is safer than sed for large restructures**: when reordering sections that account for 80%+ of file content, use the Write tool to write the complete new file in one atomic operation rather than chaining 30+ sed/Edit calls. One Write call either succeeds completely or fails completely — no partial-application bugs. The risk of silent partial-application from a long sed chain (missing a step, wrong order) outweighs the risk of a single Write failure. Verified: Write with correct content + post-write integrity checks (data-slide count, data-level values, goToSlide targets) is the correct approach for whole-file restructures.
+- **2026-04-18 weather-reporter rebuild (complete — 37 slides)**: full deck rebuilt from the plan doc at `reports/learning-journey-weather-reporter-redesign.md` using a single Write-tool operation. Final structure: Slides 1-5 (opening arc: no-correct-way → Boris GIF → vibe-vs-agentic → what-is-vibe-coding → good/bad-prompts), Slide 6 (Meet the Person TOC, 5 vertical rows), Slides 7-12 (Agents — weather reporter), Slides 13-18 (Skills — weather-fetcher + weather-svg-creator), Slides 19-23 (Context — reporter's brain), Slides 24-29 (CLAUDE.md — pocket rulebook), Slides 30-32 (Commands — the trigger), Slides 33-36 (Workflow — all five pieces), Slide 37 (Closing — "Five concepts, one running example"). LEVELS map heights updated to match new arc order: agents=17%, skills=33%, context=50%, claude-md=67%, commands=83%, workflow=100%. Journey ticks updated top→bottom: Workflow, Commands, CLAUDE.md, Context, Skills, Agents. TOC goToSlide targets: Agents=7, Skills=13, Context=19, CLAUDE.md=24, Workflow-trigger=30. Both context diagrams preserved: context-window.jpeg on slide 20, context.jpg on slide 21. All real repo file paths verified against actual files before writing (weather-agent.md, weather-orchestrator.md, weather-fetcher/SKILL.md, weather-svg-creator/SKILL.md).
 
 ## Critical Requirements