diff --git a/.claude/agents/presentation-claude-code.md b/.claude/agents/presentation-claude-code.md index f8e8c90..e6b9766 100644 --- a/.claude/agents/presentation-claude-code.md +++ b/.claude/agents/presentation-claude-code.md @@ -150,3 +150,8 @@ _Findings from previous executions are recorded here. Add new entries as bullet - **2026-04-30 slide-1 H1 rename to "Claude Code Best Practice"**: completed the deck-identity unification. Slide-1 H1 was originally "Agentic Engineering in the CLI" (preserved on 2026-04-30 during the initial rename on the theory that it was the *topic* of the talk, not the *deck name*). User explicitly corrected that judgment — they want every slide-1 surface to read as the same identity. Slide-1 H1 is now "Claude Code Best Practice" (matching ``, GitHub repo `claude-code-best-practice`, and the badge URL). Inline H1 styling preserved exactly: `style="font-size: 3.2rem; letter-spacing: -0.02em; margin-bottom: 16px;"`. **Rule**: for any future deck-rename, update slide-1 H1 as part of the same coordinated set with `<title>`, slide-1 subtitle, and identity badges — don't treat H1 as a separate "topic" surface. - **2026-04-30 deck identity surfaces (final state after rename + H1 unification)**: every visible slide-1 element now points to the same identity. (1) `<title>` = "Claude Code Best Practice"; (2) Slide-1 HTML banner comment = "SLIDE 1: Claude Code Best Practice — Title"; (3) Slide-1 H1 = "Claude Code Best Practice"; (4) Slide-1 subtitle = "Practical patterns for [Claude logo] Claude Code"; (5) GitHub badge = `github.com/shanraisshan/claude-code-best-practice`; (6) favicon = `claude-jumping.svg`. **Known echo (feature, not bug)**: subtitle's "Claude Code" repeats text from the H1 — this is the normal "[Brand] Best Practices / Practical patterns for [Brand]" pattern (e.g. "React Best Practices / Practical patterns for React") and should NOT be auto-fixed unless the user explicitly asks. Only differentiate if the user requests it (e.g. subtitle could become "Practical patterns for agentic CLI workflows" or similar). - **2026-04-30 "Models are stateless" slide inserted at position 10 (48 → 49 slides)**: new slide drawn as styled-HTML-divs (no PNG asset exists for this diagram). Approach mirrors slide-12 conventions — centered block with generous whitespace, caption strip below with bold headline + accent-color subtitle. Dialog rendered as two CSS bubble columns (User = blue left-aligned; Model = purple right-aligned; error response = pink). A dashed amber divider with "new session — context wiped" label separates the two turn-pairs to visualize the statelessness. No new CSS classes introduced — all layout done via inline styles matching the surrounding slides. Sentinel-replacement bug encountered: resolving `##SN10##` → `"11"` before the bulk n=11..48 loop caused old-slide-10 to be double-incremented to `"12"` — fixed by a targeted string replacement of the affected div. **Rule for future inserts**: when using sentinel-replace for a mix of pre-resolved and loop-resolved slides, either (a) use a distinct sentinel prefix that won't match the loop range, or (b) resolve ALL sentinels in a single final pass after all placeholders are set. The `<!-- SLIDE N: ... -->` comment for the orphaned old-slide-11 banner ("Limitations") had the literal apostrophe `we're` not the HTML entity `’` — check raw file content when pattern-matching comment strings, don't trust the HTML-encoded form. Slides 10 onwards have no `data-level` (they are pre-section content); the new slide follows this convention. Gemini mentions on slides now at positions 11 and 12 (previously 10 and 11) — still illustrative, still intentional. +- **2026-04-30 slide-10 "Models are stateless" framing correction (not structural rework)**: the original insert included a dashed amber divider labelled "new session — context wiped" between turns 2 and 3, and bubble 4 said "each conversation starts fresh". The user correctly identified both as wrong framing — they teach the audience that the problem is switching sessions (resolvable by "just don't switch"), when the actual point is that statelessness is a property of every individual API call. Fixed: (1) removed the divider entirely; (2) changed turn-2 `margin-bottom` from `20px` → `10px` so all four bubbles have a consistent `10px` gap; (3) rewrote bubble 4 to "I don't know your name — I have no memory of what you just said." (within-session language only); (4) changed bold caption from "Each call starts from zero." → "Every turn is a fresh API call." (explicit within-session framing). Harness-replay subtitle kept unchanged. **Rule**: for explainer slides whose purpose is to introduce a non-obvious problem, never add framing (dividers, captions, labels) that pre-resolves the tension. For statelessness specifically: render the dialog as ONE continuous conversation so the audience feels the puzzle of "the model forgot inside a single chat" before the deck reveals the harness as the answer. Phrasings like "each conversation starts fresh" or "new session" leak the wrong multi-session frame and must be avoided. This rule supersedes the original spec author's "perhaps a dotted divider or 'new session / new context' caption" suggestion — that suggestion was wrong. +- **2026-04-30 slide-10 vocabulary anchoring — "turn" and "inference" defined**: slide 10 is now the deck's canonical vocabulary moment for two primitives the rest of the talk relies on. (1) Bold caption changed from "Every turn is a fresh API call." → "Every turn is a fresh inference." — when a precise term is defined on the same slide, the punchline should use the precise term, not the layperson paraphrase. (2) A single-line glossary added below the red subtitle (28px top margin to sit clearly below the caption-strip group, not glued to it): "**Turn** — one user message + the model's reply. • **Inference** — one model API call. The model has no memory across inferences." Rendered as Option B (single horizontal line, `font-size: 0.9rem`, `color: #666`) because slide 10 already has heavy vertical content (title + 4 bubbles + 2-line caption strip) and side-by-side mini-cards would have over-weighted the glossary relative to the dialog. No new CSS classes introduced — all inline styles. **Rule**: when the user asks to "include a word and its definition", treat the body and the glossary as a coordinated pair — promote the word into the body (replacing any vague paraphrase), and add the definition below. Do not bolt the glossary on without updating the body text above it. +- **2026-04-30 vocabulary anchor moved from slide 10 → slide 14 (SUPERSEDES previous entry)**: the prior entry's claim that "slide 10 is the deck's canonical vocabulary moment for 'turn' and 'inference'" is no longer true. The glossary paragraph was removed from slide 10 and the formal definitions were added to slide 14 (Tool Calling sequence diagram), where the diagram with a "Language Model" column showing multiple arrows per turn makes both terms visually concrete. **Rule**: vocabulary anchors belong where the visual evidence lives, not at the slide where the concept first appears. If a later slide has a diagram that visually distinguishes the named primitives, the formal definitions go on that slide — and the earlier slides should use the layperson translation only. For "turn" and "inference", that is slide 14 (the tool-calling sequence diagram: multiple arrows to the Language Model column = multiple inferences per turn). **Caption ripple rule**: when vocabulary moves out of a slide, any precise term in that slide's body must revert to the layperson version too — otherwise the slide forward-references undefined vocabulary. Slide 10's bold caption reverted from "Every turn is a fresh inference." → "Every turn is a fresh API call." for this reason. **Treatment chosen for slide 14**: stacked two-paragraph block (one `<p>` per term, `font-size: 0.95rem`, `margin-top: 28px` from image, `gap: 12px` between paragraphs) rather than side-by-side cards — the image already fills most of the slide's width and a flex row of cards would have crowded the image's bottom edge. No new CSS classes introduced — all inline styles. +- **2026-04-30 diagram-specific count annotation added to slide 14 (Turn × 1, Inference × 2)**: added a single italic preface line above the two vocabulary definitions: "In the diagram above: **Turn × 1** · **Inference × 2**". Numbers rendered in `#C0392B` (the deck's existing red accent, matching the harness-replay subtitle on slide 10) at `font-size: 1rem; font-weight: bold` within an italic `font-size: 0.9rem; color: #666` carrier sentence. **Visual approach chosen**: separate annotation line (not parenthetical inside the term headings) — the "In the diagram above:" prefix needs room to breathe as a scoping clause; embedding it into heading text would make the headings read as conditional definitions rather than scoped counts. The annotation sits inside the same `max-width: 820px` flex container as the definitions, with a `margin-bottom: 4px` gap before the first definition paragraph. Container's `margin-top` trimmed from `28px` → `24px` to absorb the extra line without pushing definitions off-screen. No new CSS classes. **Rule**: when defining a primitive on a slide that contains a diagram, annotate the specific count that primitive has IN THAT DIAGRAM and label it "In the diagram above: ..." so the counts are read as diagram-scoped observations, not general truths (e.g., "Turn × 1" here means one turn in this example flow, not one turn in every conversation). Concrete counts force audience verification against the diagram; abstract definitions alone do not. +- **2026-04-30 etymology footnote added to slide 13 (Horse Harness — The Pivot Analogy)**: added one `<p>` immediately after the red subtitle on slide 13. Final markup: `<p style="font-size: 0.95rem; font-weight: 400; color: #666; margin: 16px 0 0; letter-spacing: 0.01em;">The origin is Old French <em>harneis</em> — gear, equipment, armor.</p>`. Italicized the source word `harneis` (not the phrase "Old French") — the source word is the unfamiliar token that benefits from visual separation; "Old French" is a standard linguistic label that reads cleanly plain. `margin-top: 16px` chosen to sit clearly below the red subtitle as a separate beat without occupying excessive vertical space. Visual register is subordinate to the main caption pair: smaller font (`0.95rem` vs `1.2rem`), muted color (`#666` vs `#C0392B`), single line. **Pedagogical pattern for analogy/metaphor slides**: when the metaphor's word has a meaningful etymology, surface it as a quiet footnote below the analogy lines. It earns the analogy a "second landing" — the metaphor isn't a stretch, it's the word's original meaning recovered. This pattern applies any time an analogy word can be grounded in literal historical meaning. **Voice-to-text correction pattern**: user said "Old France" (transcription artifact) but meant "Old French" (the correct linguistic term) — cross-referenced against the user's reference screenshot where the correct form appeared in writing. Second instance of this transcription pattern this session (first was Shayan/Cheyenne). **Rule**: when in doubt about a voice-transcribed proper noun or technical term, cross-reference any reference screenshot the user shares; corrected forms in visual material override transcribed text. diff --git a/presentation/claude-code-best-practice/index.html b/presentation/claude-code-best-practice/index.html index adb102e..bed2a97 100644 --- a/presentation/claude-code-best-practice/index.html +++ b/presentation/claude-code-best-practice/index.html @@ -513,20 +513,13 @@ </div> <!-- Turn 2: Model → User --> - <div style="display: flex; justify-content: flex-end; margin-bottom: 20px;"> + <div style="display: flex; justify-content: flex-end; margin-bottom: 10px;"> <div style="background: #f3e5f5; border: 1px solid #ce93d8; border-radius: 18px 18px 4px 18px; padding: 12px 18px; max-width: 62%; text-align: left; position: relative;"> <span style="font-size: 1rem; color: #1a1a1a;">“Okay, your name is Shayan.”</span> <span style="display: block; font-size: 0.7rem; color: #888; margin-top: 4px;">➜ to user</span> </div> </div> - <!-- Divider: new session / context wiped --> - <div style="display: flex; align-items: center; gap: 12px; margin: 4px 0 20px;"> - <div style="flex: 1; border-top: 2px dashed #e0a020; opacity: 0.7;"></div> - <span style="font-size: 0.75rem; font-weight: 600; color: #e0a020; background: #fff8e1; border: 1px solid #ffe082; padding: 3px 12px; border-radius: 999px; white-space: nowrap;">new session — context wiped</span> - <div style="flex: 1; border-top: 2px dashed #e0a020; opacity: 0.7;"></div> - </div> - <!-- Turn 3: User → Model --> <div style="display: flex; justify-content: flex-start; margin-bottom: 10px;"> <div style="background: #e3f2fd; border: 1px solid #90caf9; border-radius: 18px 18px 18px 4px; padding: 12px 18px; max-width: 62%; text-align: left;"> @@ -538,7 +531,7 @@ <!-- Turn 4: Model → User (can't remember) --> <div style="display: flex; justify-content: flex-end; margin-bottom: 0;"> <div style="background: #fce4ec; border: 1px solid #f48fb1; border-radius: 18px 18px 4px 18px; padding: 12px 18px; max-width: 72%; text-align: left;"> - <span style="font-size: 1rem; color: #1a1a1a;">“I don’t know your name — each conversation starts fresh.”</span> + <span style="font-size: 1rem; color: #1a1a1a;">“I don’t know your name — I have no memory of what you just said.”</span> <span style="display: block; font-size: 0.7rem; color: #888; margin-top: 4px;">➜ to user</span> </div> </div> @@ -546,7 +539,7 @@ </div> <!-- Caption strip — mirrors slide-12 pattern --> - <p style="font-size: 1.6rem; font-weight: 700; color: #1a1a1a; margin: 8px 0 4px; letter-spacing: -0.02em; line-height: 1.2;">Each call starts from zero.</p> + <p style="font-size: 1.6rem; font-weight: 700; color: #1a1a1a; margin: 8px 0 4px; letter-spacing: -0.02em; line-height: 1.2;">Every turn is a fresh API call.</p> <p style="font-size: 1.1rem; font-weight: 400; color: #C0392B; margin: 0; letter-spacing: 0.01em;">Memory only exists if the harness replays the transcript.</p> </div> @@ -762,6 +755,7 @@ <!-- One-liner — kept, placed below the diagram --> <p style="font-size: 1.8rem; font-weight: 700; color: #1a1a1a; margin: 12px 0 6px; letter-spacing: -0.02em; line-height: 1.2;">A horse harness. A model harness.</p> <p style="font-size: 1.2rem; font-weight: 400; color: #C0392B; margin: 0; letter-spacing: 0.01em;">The model is the horse. Raw power, no direction. The harness is everything else.</p> + <p style="font-size: 0.95rem; font-weight: 400; color: #666; margin: 16px 0 0; letter-spacing: 0.01em;">The origin is Old French <em>harneis</em> — gear, equipment, armor.</p> </div> </div> @@ -776,6 +770,14 @@ alt="Diagram showing how Claude sends a tool-call request to the harness, the harness executes it against real-world systems, and the result flows back into Claude’s context" style="max-width: 100%; max-height: 55vh; border-radius: 12px; box-shadow: 0 4px 24px rgba(0,0,0,0.12);" /> </div> + + <!-- Vocabulary definitions — anchored here because the diagram above makes both terms concrete --> + <div style="margin-top: 24px; display: flex; flex-direction: column; gap: 12px; max-width: 820px; margin-left: auto; margin-right: auto;"> + <!-- Diagram-specific count annotation — scoped to this image, not a general rule --> + <p style="font-size: 0.9rem; color: #666; margin: 0 0 4px; font-style: italic;">In the diagram above:  <strong style="font-style: normal; color: #C0392B; font-size: 1rem;">Turn × 1</strong>  ·  <strong style="font-style: normal; color: #C0392B; font-size: 1rem;">Inference × 2</strong></p> + <p style="font-size: 0.95rem; color: #444; margin: 0;"><strong style="color: #1a1a1a;">Turn</strong> — one round from the user’s view: you ask, the assistant answers. <em>The entire flow above — your request, the assistant’s tool calls, and the final reply — is one turn.</em></p> + <p style="font-size: 0.95rem; color: #444; margin: 0;"><strong style="color: #1a1a1a;">Inference</strong> — one call to the language model. The model wakes up, reads the input it was given, writes a reply, then forgets everything. <em>Every arrow touching the “Language Model” column above is a separate inference. One turn can contain many inferences.</em></p> + </div> </div> <!-- ============================================================ -->