New: Lesson 13

Author: ofriw

scripts/generate-presentation.js

@@ -182,6 +182,35 @@ For presentation slides:
 ✗ Don't include every code example from the lesson
 ✗ Don't show code without explaining its purpose
 
+HANDLING MARKDOWN TABLES (CRITICAL):
+
+Source material may contain markdown tables (pipe/dash syntax like | Col1 | Col2 |).
+Tables are NOT a valid slide format—they're unreadable at presentation scale and
+violate the one-concept-per-slide principle.
+
+ABSOLUTE RULE: NEVER put pipe/dash table syntax in code or codeComparison slides.
+NEVER use language="markdown" for content containing table structures.
+
+Instead, distill tables into appropriate slide types:
+
+1. Two-category tables → "comparison" slide (neutral=true if both sides are valid)
+   Extract the key insight from each row as a bullet point.
+
+2. List-of-items tables → "concept" slide
+   Each row becomes one bullet capturing the essential insight.
+
+3. Sequential/flow tables → "codeExecution" slide
+   Each row becomes a step with appropriate highlightType.
+
+4. Good-vs-bad tables → "comparison" slide (evaluative, neutral=false)
+   Left = weak approach, Right = strong approach.
+
+Put the FULL original table in speakerNotes.talkingPoints for instructor reference.
+The slide shows the distilled insight; the notes provide the data.
+
+NOTE: language="markdown" IS valid for prompt templates showing what to write to an
+AI (e.g., CLAUDE.md examples). It is ONLY prohibited for pipe/dash table content.
+
 CODE FORMATTING FOR PRESENTATIONS:
 
 ✓ Include natural line breaks in code and text (use \\n for newlines in JSON strings)
@@ -1460,6 +1489,34 @@ function validateLearningObjectivesWordCount(presentation) {
   };
 }
 
+/**
+ * Validate that no code/codeComparison slides contain raw markdown table syntax
+ * Tables rendered as code are unreadable at presentation scale and should be
+ * distilled into comparison/concept/codeExecution slides instead.
+ * @param {object} presentation - Generated presentation object
+ * @returns {object} Validation result with issues
+ */
+function validateNoMarkdownTablesInCode(presentation) {
+  const issues = [];
+  const tablePattern = /\|.+\|.+\|\n\|[-| ]+\|/;
+
+  for (const slide of presentation.slides) {
+    const checkCode = (code, label) => {
+      if (code && tablePattern.test(code)) {
+        issues.push({ slide: slide.title, location: label });
+      }
+    };
+
+    if (slide.type === "code") checkCode(slide.code, "code");
+    if (slide.type === "codeComparison") {
+      checkCode(slide.leftCode?.code, "leftCode");
+      checkCode(slide.rightCode?.code, "rightCode");
+    }
+  }
+
+  return { valid: issues.length === 0, issues };
+}
+
 /**
  * Generate presentation for a file
  */
@@ -1656,6 +1713,30 @@ async function generatePresentation(filePath, manifest, modifiedKeys, config) {
       );
     }
 
+    // Validate no raw markdown tables in code slides
+    // Tables rendered as <pre><code> are unreadable at presentation scale
+    const tableValidation = validateNoMarkdownTablesInCode(presentation);
+    if (!tableValidation.valid) {
+      console.log(
+        `  ❌ BUILD FAILURE: ${tableValidation.issues.length} raw markdown table(s) in code slides:`,
+      );
+      tableValidation.issues.forEach((issue) => {
+        console.log(
+          `      - Slide "${issue.slide}" (${issue.location})`,
+        );
+      });
+      console.log(
+        `  ℹ️  Distill tables into comparison/concept/codeExecution slides instead`,
+      );
+      validationErrors.push(
+        "Table validation failed - raw markdown tables found in code slides",
+      );
+    } else {
+      console.log(
+        `  ✅ No raw markdown tables in code slides`,
+      );
+    }
+
     // Validate takeaway word count (5 words or fewer)
     // CRITICAL: This validation is intentionally strict and throws an error because
     // takeaways are displayed prominently on conclusion slides and must be memorable.

scripts/output/podcasts/manifest.json

@@ -88,5 +88,11 @@
     "size": 8051,
     "tokenCount": 1931,
     "generatedAt": "2025-12-31T15:05:31.026Z"
+  },
+  "practical-techniques/lesson-13-systems-thinking-specs.md": {
+    "scriptPath": "practical-techniques/lesson-13-systems-thinking-specs.md",
+    "size": 17215,
+    "tokenCount": 4207,
+    "generatedAt": "2026-02-08T18:37:10.469Z"
   }
 }

website/docs/CLAUDE.md

@@ -60,20 +60,10 @@ title: 'Lesson Title'
 sidebar_position: X
 ---
 
-## Learning Objectives
-
-- Objective 1 (specific, measurable)
-- Objective 2
-- Objective 3
-
 ## Content
 
 [Main lesson content with examples]
 
-## Hands-On Exercise
-
-[Practical exercise with clear instructions]
-
 ## Key Takeaways
 
 - Summary point 1
@@ -142,62 +132,6 @@ This approach is preferred in TypeScript projects
 :::
 ```
 
-## Learning Objectives
-
-### Characteristics of Good Objectives
-
-- **Specific** - Clear, well-defined outcome
-- **Measurable** - Can verify if achieved
-- **Actionable** - Describes what learner will DO
-- **Relevant** - Aligned with module goals
-- **Time-bound** - Achievable within lesson scope
-
-### Examples
-
-**Good:**
-
-- "Implement effective prompt patterns for code refactoring tasks"
-- "Evaluate trade-offs between different AI coding assistants for your workflow"
-- "Design a secure architecture leveraging AI for code generation"
-
-**Bad:**
-
-- "Understand AI coding assistants" (too vague)
-- "Learn about prompting" (not measurable)
-- "Become an expert" (not specific or time-bound)
-
-## Hands-On Exercises
-
-### Exercise Guidelines
-
-- **Real-world context** - Scenarios engineers actually face
-- **Clear instructions** - What to do, expected outcome
-- **Appropriate difficulty** - Challenging but achievable
-- **Multiple paths** - Allow different valid approaches
-- **Extension opportunities** - Bonus challenges for faster learners
-
-### Example Exercise Structure
-
-```markdown
-## Hands-On Exercise: Prompt-Driven Refactoring
-
-**Scenario:** You have a legacy Node.js API with poor error handling...
-
-**Your Task:**
-
-1. Analyze the code structure
-2. Craft a prompt that guides the AI to refactor with:
-   - Proper error handling middleware
-   - Validation at API boundaries
-   - Consistent error response format
-3. Evaluate the AI-generated solution
-4. Iterate based on issues found
-
-**Expected Outcome:** Production-ready error handling that follows REST best practices
-
-**Bonus Challenge:** Add OpenTelemetry tracing to the refactored code
-```
-
 ## Content Dependencies
 
 ### Prerequisites

website/docs/practical-techniques/lesson-11-agent-friendly-code.md

@@ -48,7 +48,7 @@ Both problems feed the same exponential curve. When you accept a random AI error
 
 From [Lesson 5](/docs/methodology/lesson-5-grounding), agents discover your codebase through **agentic search**—Grep, Read, Glob. **Agents only see code they explicitly find.** When constraints scatter across files, search determines what the agent sees and what it misses.
 
-**❌ Anti-pattern (scattered constraints):**
+**Anti-pattern (scattered constraints):**
 
 ```typescript
 // File: services/auth.ts
@@ -62,7 +62,7 @@ const MIN_PASSWORD_LENGTH = 12  // ← Agent never searches for this file
 
 **What happens:** Agent searches `Grep("createUser")` → reads `services/auth.ts` → generates code accepting 3-character passwords because it never saw `MIN_PASSWORD_LENGTH`.
 
-**✅ Production pattern (co-located constraints):**
+**Production pattern (co-located constraints):**
 
 ```typescript
 // File: services/auth.ts