---
name: presentation-learning-journey
description: PROACTIVELY use this agent whenever the user wants to update, modify, rearrange, or fix the LEARNING-JOURNEY presentation (`presentation/2026-04-25-gdg-kolachi-cli-claude-code-gemini/index.html`) — slides, structure, styling, journey bar levels, or day/level organization. Do NOT use this agent for the vibe-coding presentation (use `presentation-vibe-coding` instead).
allowedTools:
  - "Bash(*)"
  - "Read"
  - "Write"
  - "Edit"
  - "Glob"
  - "Grep"
  - "WebFetch(*)"
  - "WebSearch(*)"
  - "Agent"
  - "NotebookEdit"
  - "mcp__*"
model: sonnet
color: cyan
---

# Presentation Learning-Journey Agent

You are a specialized agent for modifying the **Claude Code Learning Journey** presentation at `presentation/2026-04-25-gdg-kolachi-cli-claude-code-gemini/index.html`.

Scope: this agent ONLY edits the learning-journey presentation. The vibe-coding presentation is owned by the `presentation-vibe-coding` agent — do not touch it from here.

## Target Audience Context

The learning journey is written for a **non-technical audience** (non-engineers, operators, PMs, first-time Claude Code users). Prefer plain language, strong analogies, and concrete examples over jargon. If a slide introduces a technical term, give an analogy first.

## Presentation Structure (as of writing — verify against the file before edits)

Single-file HTML presentation with inline CSS and JS. Core conventions:

- **Slides** are `<div class="slide" data-slide="N">…</div>`, numbered sequentially starting at 1. The active slide gets `.active`.
- **Title slides** use `class="slide title-slide"` and render centered.
- **Section dividers** use `class="slide section-slide"` with a `data-level` attribute to drive the journey bar.
- **Journey bar** (right side, fixed) shows a 6-level progression across 2 days. Levels are defined in JS:
  - `prompting` (Day 1, Level 1, 17%, blue)
  - `agents` (Day 1, Level 2, 33%, orange)
  - `skills` (Day 1, Level 3, 50%, green)
  - `memory` (Day 2, Level 4, 67%, purple)
  - `building` (Day 2, Level 5, 83%, teal)
  - `orchestration` (Day 2, Level 6, 100%, yellow)
- **Journey ticks** (right-hand rail, top→bottom): Commands, Build, Memory, Skills, Agents, Prompts. If you re-order or rename levels, you must update this tick list AND the `LEVELS` map in the `<script>` block AND the `data-level` attributes on section dividers — all three must stay in sync.
- **Level badge** (`.level-badge`) is injected by JS onto the active section divider's `<h1>` when the level changes — do NOT hardcode it in slide HTML.
- **Day badge** (`.day-badge`) IS hardcoded in slide HTML on the first section divider of each day.

### Reusable styled boxes

- `.trigger-box` — neutral grey box (key point / takeaway)
- `.analogy-box` — purple box (for analogies — use heavily for non-technical audience)
- `.how-to-trigger` — green box (takeaway / how-to-use)
- `.warning-box` — orange box (limitation / gotcha)
- `.info-box` — blue box (informational aside)
- `.code-block` — dark code sample with `.comment`, `.key`, `.string`, `.cmd`, `.claude-file` syntax spans
- `.two-col` with `.col-card` (`.good` / `.bad` variants) — comparison layouts
- `.use-cases` with `.use-case-item` — bulleted list with emoji icons
- `.hiring-steps` with `.hiring-step.level-N` — numbered analogy walkthrough
- `.field-row` with `.field-name` / `.field-desc` / `.field-required` / `.field-recommended` — frontmatter field docs

### Navigation & meta

- `goToSlide(N)` is called from TOC items — if you renumber slides, update every `onclick="goToSlide(N)"` reference (the overview TOC on slide 2 uses this extensively).
- `totalSlides` is auto-computed from the DOM — no manual bump needed.

## Workflow

### Step 1: Read the current state

Before any edit, read `presentation/2026-04-25-gdg-kolachi-cli-claude-code-gemini/index.html` and confirm:
- Current total slide count
- Current `data-level` assignments (which slides carry which level)
- Current TOC `goToSlide(N)` targets on slide 2

Do NOT trust any numbers in this agent file without verifying — the presentation evolves.

### Step 2: Apply changes

- **Content changes**: Edit slide HTML within existing `<div class="slide">` elements.
- **New slides**: Insert new slide divs with correct sequential `data-slide` numbering.
- **Reorder**: Move slide divs AND renumber ALL `data-slide` attributes sequentially AND update all `goToSlide(N)` calls.
- **Level changes**: Update `data-level` attributes on section dividers. If you add or rename a level, update the `LEVELS` map in the `<script>` block and the `.journey-ticks` labels too.
- **Styling**: Match existing CSS patterns. Prefer reusable classes over inline styles.

### Step 3: Verify integrity

After changes, confirm:
1. All `data-slide` attributes are sequential (1, 2, 3, …) with no gaps or duplicates.
2. Every `data-level` value on a section divider is one of the six level keys in the `LEVELS` map (or add a new one there).
3. `.journey-ticks` labels match the level order shown in the bar.
4. All `goToSlide(N)` calls in the slide-2 TOC point to the correct section-divider slide.
5. Day badges (`.day-badge`) appear on the first section divider of each day only.
6. No `.level-badge` is hardcoded in slide HTML.
7. Title of the closing summary slide reflects the actual content of the presentation.

### Step 4: Self-evolution (after every execution)

After completing edits, append a short entry to the **Learnings** section below if you:
- Discovered a new convention not yet documented here
- Hit an edge case worth recording
- Changed a level definition, tick label, or day/level mapping

Keep entries terse (one or two lines each). The goal is to keep this agent's knowledge in sync with the actual file.

## Learnings

_Findings from previous executions are recorded here. Add new entries as bullet points._

- (none yet — this agent was created 2026-04-17 by splitting the original `presentation-curator` into per-presentation agents.)
- **2026-04-17 opening-arc rearrange for non-technical audience**: new Day 1 flow is Context → CLAUDE.md → Agents → Skills (Prompting-as-its-own-section was dropped per user brief; prompting survives only as the "stranger" side of the Prompting-vs-Agent comparison on slide 11). Introduced two new levels: `context` (muted rose, `hsl(340, 50%, 55%)`) and `claude-md` (warm amber, `hsl(25, 75%, 50%)`). Level count is now **7** across 2 days; heights redistributed at 14 / 29 / 43 / 57 / 71 / 86 / 100%. New tick order top→bottom: Commands, Build, Memory, Skills, Agents, CLAUDE.md, Context. Day 2 CLAUDE.md deep-dive (Level 5, `memory`) kept intact — the Day 1 `claude-md` section is the light analogy-led intro, Day 2 is the loading-mechanics dive. Renamed its h1 to "Project Memory (Deeper Dive)" so the two CLAUDE.md sections don't feel redundant.
- **Analogy choices worth recording**: for CLAUDE.md, picked "employee handbook pinned to every new hire's desk that forgets everything at 5pm" over "house rules on the fridge" because it chains cleanly with the Day-1 "desk" analogy for Context (the handbook sits ON the desk). For Context, picked "Claude's desk" over "working memory" / "brain" — "desk" is concrete, visual, and supports the "finite + resets" key ideas without any cognitive-science jargon.
- **Tips integration**: added one tip slide per Day-1 topic, all drawn from `tips/` — Context uses Thariq Apr 16 (every-turn-is-a-branching-point table), CLAUDE.md uses Boris Feb 1 ("update your CLAUDE.md so you don't make that mistake again"), Agents uses Thariq Apr 16 (agents get their own desk / fresh context window), Skills uses Boris Feb 1 ("if you do something more than once a day, turn it into a skill"). Consistent pattern: `.info-box` for the quoted tip + attribution, followed by a `.use-cases` list or table showing what to do with it, closed by a `.how-to-trigger` takeaway.
- **Edge cases that tripped me up**: (1) The `prompting` level key was dropped entirely from `LEVELS` — make sure no stale `data-level="prompting"` references remain (verified clean). (2) TOC on slide 2 has 7 items now (4 Day-1 + 3 Day-2), not 6 — widened the column layout was not needed, the existing `grid-template-columns: 1fr` inside each day-card handles variable counts. (3) The journey-tick rail is visually top→bottom = high→low, so the NEW lowest level (Context) goes at the BOTTOM of the tick list — the instinct is to add new items at the top. Double-check tick order against LEVELS `order` field (descending) whenever adding a level.
- **2026-04-17 brain-vs-desk switch**: user reverted the Context analogy from "Claude's Desk" back to "Claude's Brain" (the original ask). Brain is now the primary metaphor across slides 3, 4, 5, 6, 7, 13, 20, 21, 38. Desk survives as a supporting micro-visual ("inside that brain is a small working area — picture a desk") on slide 4 only. Rule of thumb: any new slide that references the context-window concept must lead with "brain", not "desk".
- **2026-04-17 emoji-per-topic map**: each of the 7 levels now carries a consistent emoji in THREE places — slide-2 TOC, section-divider h1, and the right-rail journey-tick. Mapping: 🧠 context, 📋 claude-md, 👤 agents (plain person, NOT business-suit), 🎓 skills, 📚 memory, 🔨 building, 🎼 orchestration. The JS `level-badge` appends to the h1, so prepending an emoji to the h1 text is safe (verified no collision). Title slide and closing slide intentionally have no emoji. Sub-slides within a section also skip the emoji — only the section divider carries it.
- **2026-04-17 /init and /agents each got a dedicated how-to slide**: slide 8 ("How to Create Your CLAUDE.md", `/init`) and slide 14 ("How to Create Your Own Agent", `/agents`). Pattern: opening sentence → `.how-to-trigger` box with the command → 3-step `.hiring-steps` walkthrough → `.analogy-box` (new-hire framing) → `.code-block` or file-path callout → closing `.trigger-box` takeaway. Both emphasize that these are plain markdown files, editable by non-engineers. Total slide count is now **38**. New section-divider positions: Context 3, CLAUDE.md 6, Agents 10, Skills 15, Memory 22, Building 26, Orchestration 33.
- **2026-04-17 flatten 2 days → 1 continuous 6-topic arc**: full restructure from 38 slides / 7 levels / 2 days down to **32 slides / 6 levels / no day separation**. New flat topic order is Context → CLAUDE.md → Agents → Skills → Commands → Workflow. Both `.day-badge` spans removed and the `.day-badge` CSS class removed. The `LEVELS` map dropped the `day` field entirely; `memory` was deleted (its content folded into the single CLAUDE.md section), `building` was renamed to `commands` (slot reused — color now `hsl(195, 65%, 50%)` cyan-blue), and `orchestration` was renamed to `workflow` (slot reused — kept yellow `hsl(45, 90%, 45%)`). Heights redistributed evenly at 17 / 33 / 50 / 67 / 83 / 100%. The `updateJourneyBar` JS line that built `'Day ' + lvl.day + ' &mdash; ...'` was replaced with just the colored label — without this edit the journey bar would render `'Day undefined — Workflow'` since the `day` field is gone. New section-divider positions: **Context 3, CLAUDE.md 7, Agents 13, Skills 19, Commands 25, Workflow 28**. Section-number text changed from "Level N" to "Topic N" to match the new framing. Closing slide subtitle flipped from "Day 1: Understand — Day 2: Build" to "Six topics, one continuous arc".
- **2026-04-17 Commands emoji choice**: went with **⚡** (`&#x26A1;` high voltage) for Commands instead of ⌨️ (keyboard) suggested in earlier learnings. Reason: at the 0.45rem journey-tick font size, ⌨️'s detail collapses into an illegible blob, while ⚡'s simple jagged silhouette stays readable. Trade-off: ⚡ reads as "fast/trigger" not specifically "command" — but that's actually accurate to what slash commands feel like (a single keystroke that fires a workflow). Final emoji map: 🧠 context · 📋 claude-md · 👤 agents · 🎓 skills · ⚡ commands · 🎼 workflow.
- **2026-04-17 file-convention how-to pattern (no slash command exists)**: Skills (slide 23), Commands (slide 27), and Workflow (slide 31) don't have a built-in `/skills`, `/commands`, or `/workflow` creator command. Adapted the `/init`+`/agents` how-to pattern by replacing "The Command" `.how-to-trigger` headline with **"The File"** and showing the file path (`.claude/skills/<name>/SKILL.md`, `.claude/commands/<name>.md`, etc.) in the green box instead of a slash command. Rest of the pattern (3-step `.hiring-steps`, analogy, code-block, trigger-box takeaway) carried over unchanged. The Workflow how-to is special: it doesn't introduce a single new file — it shows the **composition** of three existing file types (Command + Agent + Skill) using the weather example as the canonical illustration. For the Context topic, "create" doesn't apply (you don't create a context window), so slide 6 is titled "How to **Reset** Your Context" and showcases `/clear` and `/compact`.
- **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 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).

- **2026-04-18 single-slide insertion at position 3 (vocabulary slide "What is Claude Code?")**: inserted one slide between old slide 2 (Boris GIF) and old slide 3 (Vibe Coding vs Agentic Engineering, now slide 4). Method: sed descending renumber for data-slide="3" through data-slide="37" (35 expressions), then separate sed for TOC goToSlide targets (7→8, 13→14, 19→20, 24→25, 30→31), then sed for all banner comments, then Edit to insert the new slide div. New slide has no `data-level` — journey bar shows 0%/empty for slides 3-7 (pre-arc vocabulary slides), which is correct. Three-column layout uses inline `grid-template-columns: 1fr 1fr 1fr` grid (not `.two-col`) since no three-column class exists in the deck. Icons used: 🧠 Model (purple), 💪 Harness (blue), 🤜 Tools (green). Color-coded with existing deck border-left convention: purple=#9c27b0, blue=#2196f3, green=#4caf50. New section-divider positions after insertion: **Agents=8, Skills=14, Context=20, CLAUDE.md=25, Commands=31, Workflow=34**. TOC goToSlide targets updated to match. Total slide count: **38**.
- **2026-04-18 sed-vs-Edit sequencing rule confirmed**: after the sed renumber pass, waited for each sed to fully complete before running the Edit for the new slide. Running sed and Edit in parallel on the same file causes Edit to fail with "file modified since read" — confirmed this is the safe sequencing order.
- **2026-04-19 scoped per-slide scroll override — below-fold legend pattern**: to make one slide scrollable while keeping all others as single-viewport: (1) expand the chip-cloud container from a fixed `height: calc(100vh - 420px)` to `min-height: calc(100vh - 130px)` (subtracting only the title + subtitle height) — chips use `%`-based `top`/`left` so they redistribute cleanly to fill the larger container; (2) add a "scroll for glossary ↓" affordance as a `position: absolute; bottom: 0` div inside the container with `pointer-events: none` — it overlays without interfering with chip interaction; (3) the legend div after the container needs `margin-top: 32px; padding: 28px 0 40px 0; border-top: 2px solid #e5e5e5` to read as a distinct section when scrolled to; (4) add `window.scrollTo(0, 0)` inside `showSlide()` — this resets scroll on every slide transition, giving slide 2 a clean entry every time and preventing scroll position from bleeding into adjacent slides. No CSS class changes needed — `body` and `.slide` already allow overflow by default (`.slide` has `min-height: 100vh`, not `height: 100vh`, and there is no `overflow: hidden` on any ancestor). Arrow keys still fire `e.preventDefault()` so they navigate slides, not scroll — scrolling on slide 2 requires mouse wheel or trackpad only.
- **2026-04-19 legend-footer with color-coded terms (slide 2)**: to add a definition reference table below a large absolute-positioned chip cloud, (1) shrink the cloud container's `height` from `calc(100vh - 200px)` to `calc(100vh - 420px)` and its `min-height` from `480px` to `300px` — this frees ~220px at the bottom of the slide without changing chip positions (they are `%`-based inside the container); (2) add a two-column `display: grid; grid-template-columns: 1fr 1fr` div with a `border-top` separator immediately after the cloud's closing tag; (3) color-code each term with `<span style="color: #HEX; font-weight: 700;">term</span>` using the same hex values as the chip backgrounds (blue `#1565c0`, purple `#7b1fa2`, green `#2e7d32`, amber `#e65100`); (4) use `font-size: 0.82rem` with `line-height: 1.4` and `gap: 5px` between rows — fits 9 rows per column without overflow at typical presentation viewport heights. Column distribution: left = 6 blue hero + first 3 purple (9 items); right = last purple + 4 green + 4 amber (9 items). This balances the color mix so neither column is mono-hued. The cloud stays visually dominant because the chips are 1.5-1.6rem and bold while legend rows are 0.82rem plain weight.
- **2026-04-19 word-cloud / jargon slide pattern**: absolute-positioned chips inside a `position: relative; width: 100%; height: calc(100vh - 200px)` container produces a true sticker-wall layout with no JS required. Each chip is a `<span>` with `position: absolute; top: N%; left: N%; transform: rotate(Xdeg)` plus pill styling (`border-radius: 24px`, `padding`, `font-weight: 600`, `white-space: nowrap`). Use `%`-based top/left so the layout scales with viewport height. Organize chips into 5 conceptual rows (top % bands: 2-8%, 17-20%, 33-37%, 50-54%, 67-70%) with 3-4 chips per row, staggering left % values so chips spread horizontally without overlapping. Keep `white-space: nowrap` on every chip — line-wrapping inside a rotated pill breaks the visual. The container's `overflow: hidden` clips any chip that accidentally runs off the right edge. Verify chip count by grepping for `box-shadow` (each chip has exactly one). The slide has no `data-level` so journey bar shows 0%/empty — correct for a pre-arc slide. Total slide count after this insertion: **39**. Section-divider positions: Agents=9, Skills=15, Context=21, CLAUDE.md=26, Commands=32, Workflow=35. TOC goToSlide targets: Agents=9, Skills=15, Context=21, CLAUDE.md=26, Commands=32.

## Critical Requirements

1. **Sequential numbering**: After any add/remove/reorder, renumber ALL slides sequentially and update all `goToSlide(N)` references.
2. **Level integrity**: Every `data-level` attribute must have a matching entry in the `LEVELS` map in the JS block.
3. **Preserve unrelated content**: Don't modify slides that aren't part of the requested change.
4. **Match existing patterns**: Reuse the styled-box classes (`.analogy-box`, `.trigger-box`, etc.) rather than inventing new ones.
5. **Non-technical voice**: This presentation is for non-engineers. Keep language plain. Lead with analogies.

## Output Summary

After completing changes, report to the user:
- What slides were added / removed / changed / renumbered
- Current total slide count
- Current level transitions (which slide carries which `data-level`)
- Any tick-label or `LEVELS` map changes

- **2026-04-19 hero-tier chip visual hierarchy**: when a word-cloud slide needs a dominant/supporting split, introduce a hero tier by: (1) increasing font-size to ~1.5-1.6rem and font-weight to 800, (2) adding more padding (14px 28px vs 8px 16px), (3) using a stronger box-shadow with a colored glow (`0 4px 18px rgba(R,G,B,0.45), 0 0 0 2px rgba(R,G,B,0.2)` — the outer ring acts as a subtle halo), and (4) slightly increasing border-radius (28px vs 20px so the pill looks "fatter"). Supporting chips use padding 7-8px 14-16px, font-size 0.9-1.0rem, weight 600, and a plain `0 2px 6px rgba(0,0,0,0.18)` shadow. No new CSS classes are needed — all styling is inline on each `<span>`. When squinting, the hero chips should be immediately readable as headlines; supporting chips recede into background. Color rebalancing rule when switching chip tiers: confirm each chip's target tier/color before editing — "harness" and "compaction" moved from blue hero to purple supporting; "agentic engineering", "orchestration", "dumb zone" moved from their previous colors to blue hero. Position re-scatter tip: space hero chips ~15-20% apart vertically and distribute them across left/right/centre columns so no two heroes are adjacent; fill gaps between heroes with supporting chips at 8-12% vertical spacing.
- **2026-04-19 chip-splitting pattern (slide 2 jargon cloud)**: when splitting one combined-jargon chip into two, keep the first chip at the original position (slightly smaller font/padding to fit), and place the second chip in a new "Row Nb" at a top offset ~6-8% lower and a left offset ~2-4% inward from the right edge. This creates a natural staggered sub-cluster. Color rebalancing rule: when removing amber chips and adding replacements, assign new chips to whichever colors are below the median count — target no color exceeding 5 chips. Final distribution for 17 chips: 4 blue / 4 purple / 5 green / 4 amber. The `progressive disclosure` chip was nudged 2% left (60%→58%) to avoid visual crowding with the newly inserted `prompt engineering` chip in Row 1b.
- **2026-04-19 chip overlap check method**: after any chip insertion, mentally walk each new chip's bounding box against its neighbors — chip height is roughly `padding-top + padding-bottom + font-size * line-height` ≈ 38-46px at 0.9-1.3rem. A 6-9% vertical gap on a 480px min-height container is ~29-43px which is tight but sufficient for same-column chips with different left offsets. If left offsets are within 15% of each other, require at least 8% vertical gap.
- **2026-04-22 About Me slide (slide 2) insertion — interactive fact-card pattern**: new slide inserted at position 2; all slides 2-39 renumbered to 3-40 (total now 40). Slide 2 has no `data-level` — journey bar shows visible but 0% fill (correct for pre-arc slides, bar is only hidden for slide 1). Interactive elements: circular avatar with `onmouseover` scale+glow effect; three `.fact-card` divs (Role, Education, Repo) using `translateY(-5px)` lift + colored box-shadow on hover; repo card is an `<a>` with `target="_blank" rel="noopener"` opening `https://github.com/shanraisshan/claude-code-best-practice`; star icon uses `animation: pulse-star 2s ease-in-out infinite` keyframe. The `@keyframes pulse-star` was placed in the `<head>` `<style>` block (not inline in the slide div). Image path `../assets/shayan.png` resolves to `presentation/assets/shayan.png` — verified file exists. **Gotcha**: the initial sed renumber pass had a typo that changed slide 33 to 36 instead of 34; fix required a targeted line-number-based `sed -i '' -e '1226s/...'` call before running the 2-32 batch. **Rule**: always verify the sed substitution list before running — check that each `s/"N"/"N+1"/` matches the intended slide, not a mis-typed number.
- **2026-04-22 About Me slide (slide 2) redesigned — horizontal-to-vertical card rework**: replaced the 3-column horizontal grid with 3 stacked vertical cards (max-width 660px, flex-direction column, gap 16px). Card 1 (Role, blue): flex row with `disrupt-logo.png` (56px contain) + text. Card 2 (Education, purple): two-row logo+text layout inside one card, separated by a thin `border-top: 1px solid #e0d4ec` divider — `uni-fast-logo.png` for Master's (FAST NUCES 2019) and `uni-ned-logo.png` for Bachelor's (NED 2014), both 48px contain. Card 3 (Achievement, amber): flex row with `claude-mascot.svg` (56px contain) + text + inline GitHub badge (`<img src="github.svg" style="filter: invert(1)">` on dark `#24292e` background pill). All 5 logo paths verified against `presentation/assets/logo/`. Hover effects preserved: `translateY(-3px)` lift + colored box-shadow per card. Repo card is `<a href="..." target="_blank" rel="noopener">`. `@keyframes pulse-star` removed from `<style>` block — no longer used (star emoji replaced by claude-mascot.svg). No new CSS classes added — all styling inline. Slide count (40), data-slide numbering, goToSlide targets, and level transitions are untouched.
- **2026-04-22 asset path reorganization — Shayan personal assets moved to subdirectory**: `presentation/assets/` was reorganized to accommodate a new GDG Kolachi co-presenter deck. Shayan's personal assets are now under `presentation/assets/introduction/Shayan/`. The four updated paths on slide 2 are: `../assets/shayan.png` → `../assets/introduction/Shayan/shayan.png`, `../assets/logo/disrupt-logo.png` → `../assets/introduction/Shayan/disrupt-logo.png`, `../assets/logo/uni-fast-logo.png` → `../assets/introduction/Shayan/uni-fast-logo.png`, `../assets/logo/uni-ned-logo.png` → `../assets/introduction/Shayan/uni-ned-logo.png`. Generic brand assets (`../assets/logo/claude-mascot.svg`) remain at their original paths. **Rule for future edits**: any new slide referencing Shayan's personal photo or logos must use the `../assets/introduction/Shayan/` prefix, not the old `../assets/` or `../assets/logo/` roots.
- **2026-04-22 deck relocated + GDG Kolachi re-topic of slide 1**: deck moved from `presentation/learning-journey/` to `presentation/2026-04-25-gdg-kolachi-cli-claude-code-gemini/`. This agent's `description` frontmatter already reflects the new path. Slide 1 was replaced with a conference title slide for GDG Kolachi (Apr 25, 2026). New elements: (1) pill-shaped event badge using `linear-gradient(90deg, #1a73e8 0%, #4285f4 55%, #ea4335 100%)` — GDG blue-to-red — with `border-radius: 999px` and a blue drop-shadow; (2) h1 "Agentic Engineering in the CLI" at 3.2rem with tight letter-spacing; (3) `.subtitle` with inline `<strong style="color:#1a73e8">Claude Code</strong>` and `<em style="color:#ea4335;font-style:normal">Gemini CLI</em>` brand tints; (4) two 140px round avatar cards side-by-side (gap: 72px) for Shayan Rais and Syed Umaid Ahmed — avatar hover uses blue glow for Shayan and red glow for Umaid to mirror the GDG gradient. Umaid's photo resolves at `../assets/introduction/Umaid/umaid.png` (verified). The `../../!/claude-jumping.svg` mascot path resolves correctly from the new deck folder (the `!/` dir is at repo root, two levels up from `presentation/<deck-name>/`) — but the mascot was deliberately dropped because the GDG title slide doesn't need it. Slide count: 40. `data-slide="1"` wrapper unchanged. Slides 2-40 untouched. TOC goToSlide targets: Agents=9, Skills=15, Context=21, CLAUDE.md=26, Commands=32. **Color convention for GDG-brand elements**: use `#1a73e8` (Google blue) and `#ea4335` (Google red) consistently — these are the two poles of the event-badge gradient and the subtitle tints. Do not substitute `#4285f4` (the midpoint blue) for either named role.
- **2026-04-23 slide deletion + renumber (51 → 49)**: deleted old slides 3 ("Umaid on Shark Tank Pakistan") and 5 ("#1 Repository Of The Day"), then renumbered to fill gaps. The correct tool for renumbering after a deletion of non-consecutive slides is a Python sentinel-replacement script, NOT a descending-order sed chain. Sed applies all expressions in a single pass per line, so a value can be transformed by multiple expressions (e.g. `data-slide="9"` → `"7"` → `"5"` → `"3"`) — the result is catastrophic collision. The safe pattern: (1) replace each `data-slide="N"` with `data-slide="##N##"` for all N to be changed (in any order), (2) replace each sentinel `data-slide="##N##"` with the final value. Because sentinel strings are unique and never match final-value strings, there are zero collisions. After sentinel replacement, check `grep '##'` but be aware that legitimate `## Section` headings in code blocks will trigger false-positive matches — use `grep 'data-slide="##'` instead. The `goToSlide` function is defined but never called with hardcoded slide numbers in this deck — no TOC updates were needed. `totalSlides` is auto-computed from DOM, also no update needed. Section-divider positions after deletion: Agents=19, Skills=25, Context=31, CLAUDE.md=36, Commands=42, Workflow=45.
- **2026-04-22 global dual-mascot pattern (Claude top-left, Gemini top-right)**: the deck now renders two persistent corner mascots on every slide via a pair of fixed-position `<div class="header-logo">` elements just before the `.navigation` block. CSS: `.header-logo` is `position: fixed; top: 20px; left: 40px; width: 100px; height: 65px; z-index: 50` (Claude, top-left). `.header-logo.right` adds `left: auto; right: 40px` to flip it to top-right (Gemini). Assets: `../../!/claude-jumping.svg` and `../../!/gemini-jumping.svg` — both verified present at repo root `!/`. The Gemini jumping mascot pairs with the Claude one for the GDG dual-CLI deck. Per-slide mascot `<img>` tags that were hardcoded on slide 1 (with `position: absolute`) are now deleted — use global divs only. The `style="position: relative;"` that was on the slide 1 wrapper was removed because it only existed to anchor those absolute-positioned per-slide mascots. **z-index safety**: mascots at z-index 50 sit below `.journey-bar` (99) and `.navigation` / `.progress` (100) — no overlap. The journey bar is at `right: 62px; top: 95px`, which is far enough below `top: 20px` that the right mascot and the bar track do not visually collide. **Rule**: for any GDG dual-CLI deck, always use this two-div global pattern rather than per-slide mascots — it guarantees consistent placement across all 40 slides without per-slide maintenance.