Merge branch 'main' into podcast

Author: ofriw

scripts/generate-presentation.js

@@ -536,13 +536,22 @@ REMINDER: If the source contains prompt examples (text showing what to write to
       "speakerNotes": { ... }
     },
 
-COMPARISON SLIDE CONVENTION (CRITICAL - HARDCODED IN UI):
+COMPARISON SLIDE CONVENTION (CRITICAL - STYLING RULES):
 
-The comparison slide type has HARDCODED styling in the presentation component:
-- LEFT side → RED background, RED heading, ✗ icons (ineffective/worse/limited)
-- RIGHT side → GREEN background, GREEN heading, ✓ icons (effective/better/superior)
+The comparison slide type has TWO variants based on the "neutral" flag:
 
-YOU MUST ALWAYS follow this convention:
+1. EVALUATIVE (default, neutral=false or omitted):
+   - LEFT side → RED background, RED heading, ✗ icons (ineffective/worse/limited)
+   - RIGHT side → GREEN background, GREEN heading, ✓ icons (effective/better/superior)
+   - Use when one approach is clearly inferior to the other
+   - Examples: "Ineffective vs Effective", "Traditional vs Modern", "Limited vs Superior"
+
+2. NEUTRAL (neutral=true):
+   - BOTH sides → PURPLE background, PURPLE heading, → arrows (both valid options)
+   - Use for architectural trade-offs where both options are valid but have different characteristics
+   - Examples: "Autonomous vs Structured sub-agents", "Synchronous vs Asynchronous APIs"
+
+FOR EVALUATIVE COMPARISONS, YOU MUST ALWAYS follow this convention:
 - LEFT: The worse/ineffective/traditional/limited approach
 - RIGHT: The better/effective/modern/superior approach
 
@@ -567,6 +576,20 @@ INCORRECT: Putting the better option on the left will show it with RED ✗ styli
       },
       "speakerNotes": { ... }
     },
+    {
+      "type": "comparison",
+      "title": "Architectural Trade-offs: Option A vs Option B",
+      "neutral": true,                 // OPTIONAL: Use neutral=true for valid trade-offs (PURPLE neutral styling)
+      "left": {
+        "label": "Option A",           // Both options valid - neutral styling
+        "content": ["Point 1", "Point 2"]
+      },
+      "right": {
+        "label": "Option B",           // Both options valid - neutral styling
+        "content": ["Point 1", "Point 2"]
+      },
+      "speakerNotes": { ... }
+    },
     {
       "type": "codeComparison",
       "title": "Prompt Example: Ineffective vs Effective",

website/docs/methodology/lesson-3-high-level-methodology.md

@@ -81,6 +81,12 @@ With research complete, you now plan the change. Planning isn't a single approac
 
 <PlanningStrategyComparison />
 
+<!-- presentation-only-start -->
+
+**Planning strategy comparison - both approaches are valid depending on project phase and certainty level. Use neutral styling.**
+
+<!-- presentation-only-end -->
+
 **Exploration Planning:** Use this when the solution space is unclear or you need to discover the best approach. Rather than dictating a solution, frame the problem space and steer the agent to research your codebase patterns (via ChunkHound) and domain knowledge (via ArguSeek), explore alternatives, and iterate with you through reasoning-action cycles. You're discovering the approach together.
 
 This approach has higher cost and time investment, but it discovers better solutions, catches architectural issues early, and helps you build a clearer mental model before committing to implementation.
@@ -193,6 +199,12 @@ This template provides a solid baseline for any planning task. In [Lesson 4: Pro
 
 ## Phase 3: Execute (Two Execution Modes)
 
+<!-- presentation-only-start -->
+
+**Execution modes comparison - both approaches are valid depending on context (learning stage, task criticality, grounding quality). Use neutral styling.**
+
+<!-- presentation-only-end -->
+
 With your plan complete, you execute—but how you interact with the agent during execution fundamentally changes your productivity. There are two modes: supervised (actively watching and steering) and autonomous (fire-and-forget). Most engineers start with supervised mode to build trust, then gradually shift to autonomous mode as they develop stronger grounding and planning skills. Here's the counterintuitive truth: the real productivity gain isn't about finishing individual tasks faster. It's about working on multiple projects simultaneously and maintaining extremely long work stretches. That's where 10x productivity actually hides.
 
 ### Supervised Mode ("Babysitting")

website/docs/methodology/lesson-5-grounding.md

@@ -156,6 +156,19 @@ Example: ChunkHound uses a fixed multi-hop pipeline where the system controls tr
 
 **The architectural trade-off:** Autonomous agents work well but degrade in large codebases where they make suboptimal exploration choices. Structured agents scale reliably but cost more to build and run.
 
+<!-- presentation-only-start -->
+
+**Sub-agent architecture comparison - both approaches are valid depending on codebase scale. Use neutral styling.**
+
+| Approach A (Autonomous)                    | Approach B (Structured)                       |
+| ------------------------------------------ | --------------------------------------------- |
+| Agent decides search strategy autonomously | Deterministic control plane defines algorithm |
+| Simpler to build and maintain              | Scales reliably to millions of LOC            |
+| Works well for varied research tasks       | LLM makes tactical decisions within structure |
+| Degrades on very large codebases           | Higher cost and complexity to build           |
+
+<!-- presentation-only-end -->
+
 ### Sub-Agent Availability
 
 **Availability depends on your agent platform:**

website/src/components/PresentationMode/RevealSlideshow.module.css

@@ -243,6 +243,38 @@
   color: #51cf66;
 }
 
+/* Neutral comparison variant - uses primary color for both sides */
+.neutralLeft,
+.neutralRight {
+  composes: gpuOptimized;
+  padding: clamp(0.7em, 1.5vw, 1em);
+  border-radius: 8px;
+  overflow-y: auto;
+  background: var(--visual-bg-workflow);
+  border: 2px solid rgba(124, 58, 237, 0.3);
+}
+
+.reveal .neutralLeft,
+.reveal .neutralRight {
+  border-color: rgba(167, 139, 250, 0.3);
+}
+
+.neutralHeading {
+  color: var(--brand-primary-light);
+  font-size: clamp(0.9rem, 1.8vw, 1em);
+  margin-bottom: 0.3em;
+  font-weight: 600;
+}
+
+.neutralLeft li::before,
+.neutralRight li::before {
+  content: '→';
+  position: absolute;
+  left: 0;
+  color: var(--brand-primary-light);
+  font-weight: 600;
+}
+
 /* Marketing vs Reality - Translation Pattern */
 .marketingReality {
   display: grid;

website/src/components/PresentationMode/RevealSlideshow.tsx

@@ -56,6 +56,7 @@ interface Slide {
   code?: string;
   caption?: string;
   component?: string;
+  neutral?: boolean;
   left?: { label: string; content: string[] };
   right?: { label: string; content: string[] };
   leftCode?: { label: string; language: string; code: string };
@@ -257,8 +258,18 @@ export default function RevealSlideshow({
             <h2>{slide.title}</h2>
             <div className={styles.comparison}>
               {slide.left && (
-                <div className={styles.comparisonLeft}>
-                  <h3 className={styles.ineffective}>{slide.left.label}</h3>
+                <div
+                  className={
+                    slide.neutral ? styles.neutralLeft : styles.comparisonLeft
+                  }
+                >
+                  <h3
+                    className={
+                      slide.neutral ? styles.neutralHeading : styles.ineffective
+                    }
+                  >
+                    {slide.left.label}
+                  </h3>
                   <ul>
                     {slide.left.content.map((item, i) => (
                       <li key={i} className="fragment">
@@ -269,8 +280,18 @@ export default function RevealSlideshow({
                 </div>
               )}
               {slide.right && (
-                <div className={styles.comparisonRight}>
-                  <h3 className={styles.effective}>{slide.right.label}</h3>
+                <div
+                  className={
+                    slide.neutral ? styles.neutralRight : styles.comparisonRight
+                  }
+                >
+                  <h3
+                    className={
+                      slide.neutral ? styles.neutralHeading : styles.effective
+                    }
+                  >
+                    {slide.right.label}
+                  </h3>
                   <ul>
                     {slide.right.content.map((item, i) => (
                       <li key={i} className="fragment">

website/static/presentations/manifest.json

@@ -1,79 +1,79 @@
 {
   "intro.md": {
     "presentationUrl": "/presentations/intro.json",
-    "slideCount": 11,
-    "estimatedDuration": "35-45 minutes",
-    "title": "Operator Training: AI Coding Assistants in Production",
-    "generatedAt": "2025-11-09T10:34:22.957Z"
+    "slideCount": 10,
+    "estimatedDuration": "25-30 minutes",
+    "title": "Introduction: AI Coding Course",
+    "generatedAt": "2025-11-10T21:11:02.010Z"
   },
   "methodology/lesson-3-high-level-methodology.md": {
     "presentationUrl": "/presentations/methodology/lesson-3-high-level-methodology.json",
-    "slideCount": 12,
-    "estimatedDuration": "45-60 minutes",
-    "title": "Lesson 3: High-Level Methodology",
-    "generatedAt": "2025-11-10T15:59:19.399Z"
+    "slideCount": 10,
+    "estimatedDuration": "35-45 minutes",
+    "title": "High-Level Methodology: Research-Plan-Execute-Validate",
+    "generatedAt": "2025-11-10T21:13:53.809Z"
   },
   "methodology/lesson-4-prompting-101.md": {
     "presentationUrl": "/presentations/methodology/lesson-4-prompting-101.json",
     "slideCount": 11,
-    "estimatedDuration": "40-50 minutes",
-    "title": "Prompting 101: Pattern Completion, Not Conversation",
-    "generatedAt": "2025-11-10T19:54:29.185Z"
+    "estimatedDuration": "35-45 minutes",
+    "title": "Prompting 101: Pattern Completion Engineering",
+    "generatedAt": "2025-11-10T21:15:33.473Z"
   },
   "methodology/lesson-5-grounding.md": {
     "presentationUrl": "/presentations/methodology/lesson-5-grounding.json",
-    "slideCount": 12,
-    "estimatedDuration": "40-50 minutes",
-    "title": "Lesson 5: Grounding - Keeping AI Agents Tethered to Reality",
-    "generatedAt": "2025-11-09T06:35:22.963Z"
+    "slideCount": 15,
+    "estimatedDuration": "45-60 minutes",
+    "title": "Grounding: Anchoring Agents in Reality",
+    "generatedAt": "2025-11-11T04:24:31.477Z"
   },
   "practical-techniques/lesson-10-debugging.md": {
     "presentationUrl": "/presentations/practical-techniques/lesson-10-debugging.json",
-    "slideCount": 11,
-    "estimatedDuration": "35-45 minutes",
+    "slideCount": 10,
+    "estimatedDuration": "45-60 minutes",
     "title": "Debugging with AI Agents",
-    "generatedAt": "2025-11-10T11:19:45.844Z"
+    "generatedAt": "2025-11-10T21:39:50.140Z"
   },
   "practical-techniques/lesson-6-project-onboarding.md": {
     "presentationUrl": "/presentations/practical-techniques/lesson-6-project-onboarding.json",
-    "slideCount": 11,
+    "slideCount": 10,
     "estimatedDuration": "35-45 minutes",
-    "title": "Lesson 6: Project Onboarding - Context Files & AI Memory",
-    "generatedAt": "2025-11-09T06:37:14.278Z"
+    "title": "Project Onboarding with Context Files",
+    "generatedAt": "2025-11-10T20:39:53.491Z"
   },
   "practical-techniques/lesson-7-planning-execution.md": {
     "presentationUrl": "/presentations/practical-techniques/lesson-7-planning-execution.json",
-    "slideCount": 15,
-    "estimatedDuration": "45-50 minutes",
-    "title": "Lesson 7: Planning & Execution",
-    "generatedAt": "2025-11-10T16:44:27.800Z"
+    "slideCount": 14,
+    "estimatedDuration": "40-50 minutes",
+    "title": "Planning & Execution",
+    "generatedAt": "2025-11-10T21:21:54.387Z"
   },
   "practical-techniques/lesson-8-tests-as-guardrails.md": {
     "presentationUrl": "/presentations/practical-techniques/lesson-8-tests-as-guardrails.json",
     "slideCount": 12,
-    "estimatedDuration": "40-50 minutes",
+    "estimatedDuration": "45-60 minutes",
     "title": "Lesson 8: Tests as Guardrails",
-    "generatedAt": "2025-11-10T20:09:05.001Z"
+    "generatedAt": "2025-11-11T05:21:45.228Z"
   },
   "practical-techniques/lesson-9-reviewing-code.md": {
     "presentationUrl": "/presentations/practical-techniques/lesson-9-reviewing-code.json",
-    "slideCount": 12,
+    "slideCount": 10,
     "estimatedDuration": "35-45 minutes",
-    "title": "Lesson 9: Reviewing Code",
-    "generatedAt": "2025-11-10T16:45:53.163Z"
+    "title": "Reviewing Code with AI",
+    "generatedAt": "2025-11-10T21:25:04.301Z"
   },
   "understanding-the-tools/lesson-1-intro.md": {
     "presentationUrl": "/presentations/understanding-the-tools/lesson-1-intro.json",
     "slideCount": 11,
-    "estimatedDuration": "40-50 minutes",
-    "title": "Understanding the Tools: Lesson 1 - Introduction to AI Agents",
-    "generatedAt": "2025-11-09T11:14:16.616Z"
+    "estimatedDuration": "35-45 minutes",
+    "title": "Understanding the Machinery: LLMs and Agents",
+    "generatedAt": "2025-11-11T05:24:11.560Z"
   },
   "understanding-the-tools/lesson-2-understanding-agents.md": {
     "presentationUrl": "/presentations/understanding-the-tools/lesson-2-understanding-agents.json",
-    "slideCount": 12,
-    "estimatedDuration": "35-45 minutes",
+    "slideCount": 11,
+    "estimatedDuration": "35-50 minutes",
     "title": "Understanding Agents",
-    "generatedAt": "2025-11-10T14:57:50.229Z"
+    "generatedAt": "2025-11-10T17:58:00.131Z"
   }
 }