-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 `` tags inside `.col-card` elements when the first already captures the idea.
+- **2026-04-18 analogy-box trim pattern**: for analogy boxes with two `
` 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 `
` rather than a second `
`.
+- **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 `
` 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 && 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