diff --git a/COLORING-BOOK-SCRIPT.md b/COLORING-BOOK-SCRIPT.md new file mode 100644 index 0000000..5b63d12 --- /dev/null +++ b/COLORING-BOOK-SCRIPT.md @@ -0,0 +1,524 @@ +# AI-Assisted Development Nightmares + +## The Coloring Book - A Sequel to "Reliability Nightmares" + +**Concept**: Jeremy Eder +**Format**: Following the structure of "Reliability Nightmares" coloring book + +--- + +## Overview + +This is a follow-on to the SRE "Reliability Nightmares" coloring book. Same restaurant setting (Gino's), but now Leo faces a new challenge: his development team is drowning in routine work while competitors ship faster. Celebrity chef Cookie Cache returns—this time as an AI-assisted development coach. + +**Target Audience**: Software engineers and engineering leaders evaluating AI-assisted development + +**Narrative Arc**: Five challenges over five days, each introducing an AI-assisted development pattern + +--- + +## The Setup (Pages 1-4) + +### Page 1: Title Page + +**AI-Assisted Development Nightmares** +*The Coloring Book* + +Script and storyboard by [TBD] +Illustration by [TBD] +Concept and technical information by Jeremy Eder + +--- + +### Page 2: The Problem + +**Narration**: Gino's restaurant was thriving again after Leo learned managed service operations. But Leo had a new problem—his software development team. + +**Scene**: Leo looking stressed at a computer, surrounded by sticky notes. Multiple browser tabs open. A Slack notification says "PR waiting 3 days for review." + +**Dialog bubbles**: + +- Developer 1: "I spent all day on a typo fix. The PR process took longer than the fix." +- Developer 2: "The new hire asked how to format code. I said 'look at what we usually do.' They looked confused." +- Developer 3: "I've been waiting a week for someone to review my 50-line change." + +--- + +### Page 3: The Nightmares + +**Scene panels showing developer frustrations**: + +| Panel | Nightmare | Visual | +|-------|-----------|--------| +| 1 | Inconsistent code style | Two PRs with wildly different formatting, both "approved" | +| 2 | Forgotten conventions | New developer commits directly to main, CI breaks | +| 3 | Stale issues piling up | GitHub issues board with 200+ open issues, cobwebs | +| 4 | PR review bottleneck | Developer waiting at desk, clock spinning, "Review requested 5 days ago" | +| 5 | Dependency rot | Alert: "47 Dependabot PRs waiting" | + +**Leo (thought bubble)**: "We fixed reliability. Now we're drowning in process." + +--- + +### Page 4: Cookie Cache Returns + +**Scene**: Knock at door. Cookie Cache enters, now wearing a tech hoodie over chef outfit. + +**Cookie Cache**: "Leo! Your sister Mia called again. She says your dev team is burning out while your competitors ship features weekly. I've been studying something new—AI-assisted development. Want to give it a go?" + +**Leo**: "AI? Isn't that going to replace my developers?" + +**Cookie Cache**: "No—it's going to *amplify* them. Just like we made Gino's run like a managed service, we'll make your development team run like a well-oiled machine. Five challenges, five days. Ready?" + +--- + +## Challenge #1: The Codebase Agent (Pages 5-7) + +### Page 5: The Problem + +**Cookie Cache**: "The first challenge is consistency. Right now, every developer uses AI assistants differently. Some get great results, some get chaos. We need a Codebase Agent." + +**Leo**: "What's that?" + +**Cookie Cache**: "Think of it as a recipe book for your AI assistant. It knows your coding style, your testing conventions, and when to stop and ask for help." + +**Scene**: Split panel showing two developers using AI: + +- Left: "Write me a function" → AI outputs spaghetti code +- Right: "Write me a function" (with CBA) → AI outputs clean, tested, documented code + +--- + +### Page 6: The Solution + +**Cookie Cache**: "We create a single file that defines how AI works in your codebase." + +**Visual**: A document labeled `.claude/agents/codebase-agent.md` with sections: + +1. **Capability boundaries** - What the agent can/can't do +2. **Workflow definitions** - Step-by-step processes +3. **Quality gates** - Linting, testing, review requirements +4. **Safety guardrails** - When to stop and ask humans + +**Leo**: "So every developer gets the same AI behavior?" + +**Cookie Cache**: "Exactly. Junior devs get senior-level assistance. Senior devs get consistency. Everyone follows the same process." + +--- + +### Page 7: The Payoff + +**Scene**: Before/After comparison + +**Before**: Three developers, three different coding styles, confused code reviewer + +**After**: Three developers, consistent code, happy code reviewer saying "These all look like they came from the same team!" + +**Key points** (in callout boxes): + +- ✅ Consistency across all AI-assisted changes +- ✅ Auditability - clear trail of what the agent did +- ✅ Safety - human review gates prevent runaway automation + +--- + +## Challenge #2: Memory System (Pages 8-10) + +### Page 8: The Problem + +**Cookie Cache**: "Challenge two: your AI keeps forgetting your conventions. Every session starts from scratch." + +**Leo**: "Yeah, I have to re-explain our architecture every single time." + +**Scene**: Developer talking to AI, frustrated + +**Developer**: "No, we use the service layer for business logic, not the API layer! I told you this yesterday!" + +**AI (robot bubble)**: "I apologize for the confusion. Could you explain your architecture again?" + +--- + +### Page 9: The Solution + +**Cookie Cache**: "We create a Memory System—modular context files that give AI project-specific knowledge." + +**Visual**: File tree showing: + +```text +.claude/context/ +├── architecture.md ← "How our layers work" +├── security-standards.md ← "Validate at boundaries" +├── testing-patterns.md ← "Unit, integration, E2E" +``` + +**Cookie Cache**: "Instead of dumping your entire codebase into the prompt, you load what's relevant. 'Load the security context and review this auth PR.'" + +**Leo**: "So it remembers across sessions?" + +**Cookie Cache**: "Better—it remembers across your entire team. Update one context file, every session benefits." + +--- + +### Page 10: The Payoff + +**Scene**: Developer working smoothly with AI + +**Developer**: "Add an endpoint to the user service." + +**AI**: "I'll add the route in the API layer, business logic in the service layer, and Pydantic model in models. I'll follow your existing patterns from the architecture context." + +**Developer**: "Perfect. That's exactly right." + +**Key points**: + +- ✅ Token efficiency - only load relevant context +- ✅ Knowledge capture - tribal knowledge in machine-readable format +- ✅ Faster onboarding - new engineers (and AI) get up to speed faster + +--- + +## Challenge #3: Self-Review Reflection (Pages 11-13) + +### Page 11: The Problem + +**Cookie Cache**: "Challenge three: your AI presents sloppy first drafts. Users waste time catching obvious issues." + +**Scene**: Developer looking at AI output, facepalming + +**Developer**: "There's no input validation. There's no error handling. Did you even think about this?" + +**AI**: "Here's your code! 🎉" + +**Leo**: "That's...exactly what happens. We spend more time fixing AI output than we would have writing it ourselves." + +--- + +### Page 12: The Solution + +**Cookie Cache**: "We add a self-review step. Before presenting any work, the AI reviews its own output as if it were a code reviewer." + +**Visual**: Flowchart + +```text +Agent Does Work → Self-Review Check → Issues Found? + ↓ Yes: Fix Issues, loop back + ↓ No: Present to User +``` + +**Cookie Cache**: "The AI asks itself: 'What would a senior engineer critique? What edge case am I missing?'" + +**Sample prompt box**: + +```markdown +## Self-Review Protocol +Before presenting your work: +1. Re-read as if you're a code reviewer +2. Check for security issues, edge cases, incomplete reasoning +3. Fix any issues found +4. Note what you caught: "Self-review: Fixed [issue]" +``` + +--- + +### Page 13: The Payoff + +**Scene**: Developer receiving polished AI output + +**AI**: "Here's your code. Self-review: Added input validation for empty strings, added error handling for network failures, and noted the assumption about timezone handling." + +**Developer**: "This is actually...really good. First try." + +**Key points**: + +- ✅ Higher quality first attempts +- ✅ Reduced iteration cycles +- ✅ Visible quality process + +--- + +## Challenge #4: Proactive GHA Workflows (Pages 14-18) + +### Page 14: The Problem + +**Cookie Cache**: "Challenge four: your team spends hours on toil—reviewing trivial PRs, converting issues to PRs by hand, merging dependency updates, cleaning up stale issues." + +**Leo**: "I have 47 Dependabot PRs waiting. We never get to them." + +**Scene**: Developer drowning in notifications + +**Notifications pouring in**: + +- "Dependabot: Bump lodash from 4.17.20 to 4.17.21" +- "Issue #234 needs triage" +- "PR #456 waiting for review (7 days)" +- "Issue #123 inactive for 90 days" + +--- + +### Page 15: Issue-to-PR Automation + +**Cookie Cache**: "First pattern: when a well-defined issue is created, AI automatically analyzes it and creates a draft PR." + +**Visual**: Flowchart + +```text +Issue Opened → AI Analyzes → Clear Requirements? + ↓ Yes: Create Draft PR + ↓ No: Request Clarification +``` + +**Leo**: "So the issue becomes a PR automatically?" + +**Cookie Cache**: "A *draft* PR. Humans still review and merge. But the grunt work of creating the branch, writing initial code, linking the PR—that's automated." + +--- + +### Page 16: PR Auto-Review + +**Cookie Cache**: "Second pattern: AI reviews every PR automatically." + +**Scene**: PR with AI review comment + +**AI Review Comment**: + +- 🔴 CRITICAL: SQL injection vulnerability on line 45 +- 🟡 WARNING: Missing error handling in catch block +- ✅ GOOD: Clean separation of concerns + +**Developer**: "The AI caught a security issue before I even looked at it." + +**Cookie Cache**: "Human reviewers see AI analysis first. They can focus on architecture and design, not typos and obvious bugs." + +--- + +### Page 17: Dependabot Auto-Merge & Stale Issues + +**Cookie Cache**: "Third pattern: patch-level dependency updates auto-merge after CI passes." + +**Visual**: Dependabot PR → CI Passes → Auto-Merge (for patches only) + +**Cookie Cache**: "Fourth pattern: issues inactive for 30+ days get labeled stale. After 7 more days, they close automatically." + +**Visual**: Old issue → "Stale" label → 7 days → Closed (with exempt labels: pinned, security, bug) + +**Leo**: "So my 200 stale issues will clean themselves up?" + +**Cookie Cache**: "Yep. And important issues are protected with exempt labels." + +--- + +### Page 18: The Payoff + +**Scene**: Clean GitHub board, happy team + +**Before**: 200 issues, 47 Dependabot PRs, overwhelmed team +**After**: 30 active issues, 0 dependency backlog, focused team + +**Key points**: + +- ✅ Reduced toil +- ✅ Consistent process +- ✅ Human focus on judgment-required work + +--- + +## Challenge #5: Issue-to-PR Automation (Full Cycle) (Pages 19-21) + +### Page 19: The Problem + +**Cookie Cache**: "Final challenge: routine fixes take disproportionate time. A 2-minute typo fix becomes a 20-minute PR ceremony." + +**Leo**: "Context switch, remember linters, write commit message, create PR, wait for CI..." + +**Scene**: Developer fixing one typo, surrounded by process steps + +**Timeline**: + +- 0:00 - Find typo +- 0:02 - Fix typo +- 0:05 - Run linters +- 0:08 - Write commit message +- 0:12 - Create PR +- 0:15 - Wait for CI +- 0:20 - Request review + +--- + +### Page 20: The Solution + +**Cookie Cache**: "With Issue-to-PR automation at full autonomy, the entire cycle happens without human intervention." + +**Visual**: Issue labeled `cba:auto-fix` → CBA analyzes → Creates branch → Fixes code → Runs linters → Runs tests → Creates PR → Links to issue + +**Cookie Cache**: "You write the issue, add a label, and come back to a ready-to-merge PR." + +**Risk categories table**: + +| Risk Level | Auto-fix? | Examples | +|------------|-----------|----------| +| Low | ✅ Yes | Formatting, linting, unused imports | +| Medium | PR only | Refactoring, test additions | +| High | Report only | Breaking changes, security code | + +--- + +### Page 21: The Payoff + +**Scene**: Developer checking GitHub, pleasantly surprised + +**Developer**: "I filed an issue for that lint fix at 9am. It's 9:05 and there's already a PR. Tests pass. Ready to merge." + +**Leo**: "That used to take half a day." + +**Key points**: + +- ✅ 10x productivity for routine tasks +- ✅ Democratized automation - anyone can trigger fixes +- ✅ Audit trail - every change tracked via GitHub + +--- + +## The Wedding Reception Redux (Pages 22-24) + +### Page 22: Cookie Cache Leaves + +**Cookie Cache**: "Leo, you've learned the five challenges. Your dev team is ready." + +**Narration**: Cookie Cache left at the end of day five. In the months that followed, Leo's team put the lessons into practice... + +--- + +### Page 23: The Payoff - Each Challenge in Action + +**#1 Codebase Agent** +New hire onboarded in one day. The CBA taught them the conventions automatically. + +**#2 Memory System** +Complex refactoring succeeded because the AI understood the architecture from context files. + +**#3 Self-Review Reflection** +First-pass PR approval rate went from 40% to 85%. + +**#4 Proactive GHA Workflows** +200 stale issues cleaned up. Dependabot backlog eliminated. Team focused on features. + +**#5 Issue-to-PR Automation** +Routine fixes that took half a day now take 5 minutes. Team ships weekly instead of monthly. + +--- + +### Page 24: The Happy Ending + +**Scene**: Leo's team shipping features, competitors struggling + +**Competitor (thought bubble)**: "How are they shipping so fast?" + +**Leo's team**: Relaxed, focused, productive + +**Leo**: "Dad would be proud. We're not just running a reliable restaurant—we're building a reliable development team." + +**Tagline**: "The goal isn't to replace engineers—it's to amplify them." + +--- + +## Self-Assessment (Pages 25-26) + +### Page 25: Rate Your Team + +**Codebase Agent** +1...2...3...4...5 + +| 1 | 5 | +|---|---| +| Every dev uses AI differently, inconsistent results | Single CBA definition, consistent behavior across team | + +**Memory System** +1...2...3...4...5 + +| 1 | 5 | +|---|---| +| AI forgets conventions every session | Modular context files, tribal knowledge captured | + +**Self-Review Reflection** +1...2...3...4...5 + +| 1 | 5 | +|---|---| +| AI outputs need extensive human cleanup | AI catches own issues, polished first drafts | + +**Proactive GHA Workflows** +1...2...3...4...5 + +| 1 | 5 | +|---|---| +| Manual PR reviews, stale issues pile up | Automated reviews, auto-merge, stale cleanup | + +**Issue-to-PR Automation** +1...2...3...4...5 + +| 1 | 5 | +|---|---| +| 20 minutes of ceremony for 2-minute fixes | Routine fixes automated end-to-end | + +--- + +### Page 26: Score Yourself + +**How many points did you get? Add them up!** + +| Score | Level | +|-------|-------| +| 0-10 | Beginner - Start with the Codebase Agent | +| 11-20 | Advanced - Add Memory System and Self-Review | +| 21+ | Expert - Full automation, ship weekly | + +**Call to action**: + +- Reference Repository: github.com/jeremyeder/reference +- Working Demo: github.com/jeremyeder/demo-fastapi + +**Tagline**: "Stable, Secure, Performant, and Boring" + +--- + +## Production Notes + +### Visual Style + +- Same illustrator as original (Wildfire) if possible +- Continue the Gino's restaurant setting +- Tech elements: laptops, GitHub UI, code snippets +- Keep it lighthearted, not intimidating + +### Page Count + +- 26-30 pages (matching original) +- Each challenge: 2-3 pages + +### Coloring Elements + +- Dashboard screens (fill in metrics) +- Code blocks (syntax highlighting by coloring) +- Workflow diagrams (color the arrows) +- Character expressions (stress → relief) + +### Key Differences from Original + +- Original: SRE/reliability concepts +- Sequel: AI-assisted development patterns +- Same setting, same characters, new domain +- Maintains "Cookie Cache as coach" narrative device + +--- + +## Appendix: Mapping to Reference Repo Features + +| Coloring Book Challenge | Reference Repo Feature | +|------------------------|------------------------| +| #1 Codebase Agent | Feature 1: CBA | +| #2 Memory System | Feature 2: Memory System | +| #3 Self-Review Reflection | Feature 8: Self-Review Reflection | +| #4 Proactive GHA Workflows | Feature 9: Proactive GHA Workflows | +| #5 Issue-to-PR (Full Cycle) | Feature 3: Issue-to-PR Automation | + +Note: Features 4-7 (Architecture, Security, Testing, CI/CD for Docs) are foundational patterns that enable the five challenges but don't get dedicated chapters. They can be mentioned in context files or as supporting material.