dojo.md 0.1.0 → 0.2.1

package/courses/github-pr-review/scenarios/level-5/review-devtools-product.yaml

@@ -0,0 +1,71 @@
+meta:
+  id: review-devtools-product
+  level: 5
+  course: github-pr-review
+  type: output
+  description: "Build a review DevTools product — design and launch a code review SaaS product as a startup co-founder"
+  tags: [github, pr-review, product, startup, SaaS, go-to-market, master]
+
+state: {}
+
+trigger: |
+  You're the co-founder/CPO of a startup building "ReviewIQ" — an
+  AI-powered code review platform. You've raised $5M in seed funding
+  and have 12 months of runway. Your thesis: code review is broken at
+  scale and the market is ready for a purpose-built solution.
+
+  Market analysis:
+  - TAM: $4.2B (developer productivity tools market)
+  - SAM: $800M (code review and quality tools)
+  - SOM: $80M (AI-powered review for GitHub-based teams)
+  - Competitors: CodeRabbit ($12M ARR), Sourcery ($5M ARR), GitHub
+    Copilot code review (free, basic), Graphite (focused on stacking)
+  - Gap: No tool combines AI review + analytics + workflow automation
+    in a single platform
+
+  Product vision:
+  1. AI Reviewer: Catches bugs, security issues, and style violations
+     with <5% false positive rate
+  2. Review Analytics: Team-level and org-level metrics with benchmarks
+  3. Smart Assignment: Expertise-based reviewer assignment with load
+     balancing
+  4. Review Workflow: Custom review workflows (different rules per repo,
+     team, risk level)
+  5. Developer Experience: Integrates into GitHub's native review UI
+
+  Technical constraints:
+  - Must work with GitHub (80% of target market)
+  - Customer code must never leave their environment (enterprise
+    requirement)
+  - Must handle repos with 500K+ lines without timeout
+  - Must work with monorepos and polyglot codebases
+
+  Go-to-market constraints:
+  - 12-month runway ($5M, burn rate $400K/month)
+  - 6-person engineering team (including you)
+  - Need to reach $1M ARR to raise Series A
+  - Developer-led growth (PLG) is the primary motion
+
+  Task: Design the complete product strategy. Write: the product
+  roadmap (MVP scope for Month 1-3, growth features for Month 4-8,
+  enterprise features for Month 9-12), the technical architecture
+  (handle the privacy constraint with on-prem or edge deployment), the
+  pricing strategy (free tier, team, enterprise — with specific limits),
+  the PLG go-to-market plan (developer adoption → team adoption →
+  enterprise sale), and the competitive positioning (how to win against
+  GitHub Copilot's free review and funded competitors). Include the
+  metrics dashboard for the board and the 12-month financial projection.
+
+assertions:
+  - type: llm_judge
+    criteria: "MVP scope is achievable by a 6-person team in 3 months — focuses on one killer feature (likely AI review or analytics, not everything), defers enterprise features, and the scope decision is justified with competitive analysis"
+    weight: 0.35
+    description: "Achievable MVP scope"
+  - type: llm_judge
+    criteria: "Technical architecture solves the privacy constraint — proposes a viable approach for keeping customer code private (edge deployment, customer-hosted inference, or GitHub App with minimal data transmission), and this doesn't compromise the AI quality"
+    weight: 0.35
+    description: "Privacy-solving technical architecture"
+  - type: llm_judge
+    criteria: "GTM strategy reaches $1M ARR in 12 months — the PLG funnel is realistic (free users → team conversion → enterprise expansion), pricing tiers incentivize team adoption, and the competitive positioning against GitHub Copilot is credible (not just 'we're better')"
+    weight: 0.30
+    description: "ARR-reaching GTM strategy"

package/courses/github-pr-review/scenarios/level-5/review-industry-benchmarks.yaml

@@ -0,0 +1,64 @@
+meta:
+  id: review-industry-benchmarks
+  level: 5
+  course: github-pr-review
+  type: output
+  description: "Publish industry benchmarks — create the definitive 'State of Code Review' report with cross-industry analysis and strategic insights"
+  tags: [github, pr-review, benchmarks, research, industry-analysis, master]
+
+state: {}
+
+trigger: |
+  You're the Head of Engineering Research at a developer tools company
+  publishing the annual "State of Code Review 2026" report. This report
+  is read by 50,000+ engineering leaders and influences industry
+  practices. You have survey data from 2,500 organizations.
+
+  Raw data highlights:
+  - Average merge time by company size:
+    Startup (<50 eng): 0.8 days | Mid (50-500): 2.1 days |
+    Enterprise (500+): 4.3 days
+  - Review practices adoption:
+    Required reviews: 89% | CODEOWNERS: 52% | AI review tools: 34% |
+    Review training: 18% | Review metrics: 27%
+  - Developer satisfaction with review:
+    Very satisfied: 15% | Satisfied: 35% | Neutral: 25% |
+    Dissatisfied: 18% | Very dissatisfied: 7%
+  - Correlation data:
+    Teams with review training: 2.3x fewer review-related incidents
+    Teams using AI review: 35% faster first review, no change in bug
+    detection rate
+    Teams with stale review dismissal: 40% fewer post-merge issues
+    Teams tracking review metrics: 1.8x faster improvement velocity
+  - Industry breakdown (merge time):
+    Fintech: 3.2 days | Healthcare: 4.8 days | SaaS: 1.5 days |
+    Gaming: 0.9 days | Government: 7.1 days | E-commerce: 1.8 days
+  - Emerging trends:
+    28% considering "review-free" paths for AI-generated code
+    45% exploring AI as first reviewer before human review
+    62% report "review fatigue" as top developer experience issue
+    33% have reduced required approvals in the last year
+
+  Task: Write the "State of Code Review 2026" report. Include: the
+  executive summary (key findings in 1 page), the benchmarking
+  methodology (how data was collected, limitations, statistical
+  significance), the cross-industry analysis (why healthcare and
+  government are slow, what gaming and SaaS do differently), the
+  emerging trends analysis (AI review, review-free paths, review
+  fatigue — with predictions), and the strategic recommendations by
+  company size. Each section should include data visualizations
+  described in text and key takeaways.
+
+assertions:
+  - type: llm_judge
+    criteria: "Benchmarking methodology is credible — describes data collection, sample sizes, statistical methods, and explicitly states limitations (survival bias, self-selection, correlation ≠ causation). The methodology section would withstand peer review"
+    weight: 0.35
+    description: "Credible benchmarking methodology"
+  - type: llm_judge
+    criteria: "Cross-industry analysis reveals insights — explains why industries differ (healthcare: compliance overhead, gaming: rapid iteration culture, government: audit requirements), identifies transferable practices, and doesn't just present data but interprets it"
+    weight: 0.35
+    description: "Insightful cross-industry analysis"
+  - type: llm_judge
+    criteria: "Predictions and recommendations are bold but grounded — makes specific predictions about AI review adoption, review-free paths, and review fatigue trends, with recommendations tailored by company size and industry. Addresses the controversial 'review-free for AI code' trend thoughtfully"
+    weight: 0.30
+    description: "Bold grounded predictions"

package/courses/github-pr-review/scenarios/level-5/review-ma-integration.yaml

@@ -0,0 +1,76 @@
+meta:
+  id: review-ma-integration
+  level: 5
+  course: github-pr-review
+  type: output
+  description: "M&A review integration — harmonize code review processes across acquired companies with different engineering cultures"
+  tags: [github, pr-review, M&A, integration, culture, harmonization, master]
+
+state: {}
+
+trigger: |
+  You're the CTO overseeing the technical integration of 3 recently
+  acquired companies into the parent company. Each has a radically
+  different code review culture, and you need to create a unified
+  review process that preserves the best of each while meeting the
+  parent company's compliance requirements.
+
+  Parent company (800 engineers):
+  - GitHub Enterprise, strict 2-reviewer requirement
+  - CODEOWNERS, branch protection, SOC 2/PCI DSS compliance
+  - Average merge time: 2 days, developer satisfaction: 72%
+  - Strong tooling: automated review assignment, SLA tracking, analytics
+  - Weakness: perceived as "bureaucratic" by some teams
+
+  Acquisition A — Fast-moving SaaS startup (120 engineers):
+  - GitHub Cloud, 1-reviewer requirement, frequent self-merges
+  - No CODEOWNERS, minimal branch protection
+  - Average merge time: 4 hours, developer satisfaction: 85%
+  - Culture: "Ship fast, fix fast," trunk-based development
+  - Strength: Incredible velocity. Weakness: 3x incident rate
+
+  Acquisition B — Enterprise security company (200 engineers):
+  - GitLab self-hosted, 3-reviewer requirement including mandatory
+    security review
+  - Average merge time: 8 days, developer satisfaction: 45%
+  - Culture: "Every line must be perfect." Zero incidents but very slow
+  - Strength: Security rigor. Weakness: Engineering burnout, 30% attrition
+
+  Acquisition C — AI/ML research lab (80 engineers):
+  - Mix of GitHub and Jupyter notebooks in shared drives
+  - No formal review process — pair programming and "demo day" reviews
+  - No merge times (no PRs), developer satisfaction: 90%
+  - Culture: Academic, collaborative, experimental
+  - Strength: Innovation. Weakness: Production code quality varies wildly
+
+  Integration constraints:
+  - Must unify on GitHub Enterprise within 12 months
+  - Must achieve SOC 2 compliance across all entities within 18 months
+  - Must not lose more than 10% of acquired talent (especially from A
+    and C where culture change risk is highest)
+  - Must maintain each acquisition's product velocity during integration
+  - Budget: $1.5M for integration tooling and training
+
+  Task: Design the M&A review integration strategy. Write: the
+  assessment of each acquisition's review culture (strengths to preserve,
+  gaps to close), the unified review framework (minimum standard +
+  team-specific extensions), the migration plan for each acquisition
+  (phased, with specific milestones and risk mitigations), the culture
+  integration approach (how to merge 4 different review cultures without
+  destroying what works), and the retention risk mitigation plan.
+  Include the 18-month timeline and the executive dashboard for tracking
+  integration progress.
+
+assertions:
+  - type: llm_judge
+    criteria: "Assessment preserves strengths — Acquisition A's velocity practices are identified for adoption (not just compliance), B's security rigor informs the security review standard, and C's collaborative culture inspires pair/mob programming practices. Integration isn't one-way assimilation"
+    weight: 0.35
+    description: "Strength-preserving assessment"
+  - type: llm_judge
+    criteria: "Migration plans are tailored — A gets gradual compliance addition without killing velocity (start with CODEOWNERS, then branch protection), B gets process streamlining (reduce from 3 to 2 reviewers, optimize security review), C gets formalization without bureaucracy (lightweight PR process for production code, freedom for research)"
+    weight: 0.35
+    description: "Tailored migration plans"
+  - type: llm_judge
+    criteria: "Retention risk is specifically addressed — identifies flight risks (A's engineers who value speed, C's researchers who value freedom), proposes specific retention mechanisms (cultural ambassadors, review process autonomy periods, transparent timeline), and the 10% attrition target is tracked"
+    weight: 0.30
+    description: "Specific retention risk mitigation"

package/courses/github-pr-review/scenarios/level-5/review-regulatory-landscape.yaml

@@ -0,0 +1,78 @@
+meta:
+  id: review-regulatory-landscape
+  level: 5
+  course: github-pr-review
+  type: output
+  description: "Navigate the regulatory landscape for code review — analyze how global regulations shape review requirements and prepare for emerging compliance frameworks"
+  tags: [github, pr-review, regulatory, compliance, global, master]
+
+state: {}
+
+trigger: |
+  You're the Chief Compliance Officer of a global software company
+  operating in 35 countries. You need to map the regulatory landscape
+  for code review and change management, as regulations increasingly
+  require demonstrable software quality controls.
+
+  Current regulatory requirements affecting code review:
+
+  1. EU AI Act (effective 2026):
+  - High-risk AI systems require documented development processes
+  - Code changes to AI models need traceable review and testing
+  - Your AI-powered recommendation engine and fraud detection system
+    are classified as "high-risk"
+  - Penalty: up to 7% of global annual turnover
+
+  2. SEC Cybersecurity Rules (2024+):
+  - Material cybersecurity incidents must be disclosed within 4 days
+  - Board must demonstrate oversight of cybersecurity risk management
+  - Code review is part of the "reasonable controls" expectation
+  - Your financial reporting software processes $50B annually
+
+  3. DORA (Digital Operational Resilience Act, EU):
+  - ICT change management must be documented and tested
+  - Third-party ICT risk (including code review tools) must be managed
+  - Incident response must include root cause analysis of code changes
+  - Applies to your financial services customers in the EU
+
+  4. India's DPDP Act + China's PIPL:
+  - Data processing code changes must have privacy review
+  - Cross-border data flow code must have additional scrutiny
+  - You have engineering teams in Bangalore and Shanghai
+
+  5. Proposed US legislation:
+  - "Software Liability Act" draft would make companies liable for
+    known vulnerabilities that passed code review
+  - Bipartisan support, expected to pass within 2 years
+  - Would require "reasonable review practices" (undefined)
+
+  Emerging trends:
+  - Supply chain security regulations (NIST SSDF, EU CRA)
+  - AI-specific code review requirements (model governance)
+  - "Software bill of materials" requirements affecting dependency PRs
+  - Insurance underwriters requiring code review evidence for cyber
+    insurance renewals
+
+  Task: Map the regulatory landscape. Write: the regulatory matrix
+  (which regulations apply to which codebases, by jurisdiction and risk
+  level), the compliance gap analysis (where current review practices
+  fall short), the unified compliance framework (one review process
+  that satisfies all applicable regulations), the future-proofing
+  strategy (how to prepare for proposed and emerging regulations), and
+  the executive brief for the board on regulatory risk and investment
+  needed. Include the timeline for compliance milestones and the
+  consequences of non-compliance.
+
+assertions:
+  - type: llm_judge
+    criteria: "Regulatory matrix is comprehensive — maps each regulation to affected codebases, identifies overlapping requirements (e.g., EU AI Act + DORA both require documentation), and notes jurisdictional complexity (different requirements in EU, US, India, China)"
+    weight: 0.35
+    description: "Comprehensive regulatory matrix"
+  - type: llm_judge
+    criteria: "Unified framework satisfies all regulations efficiently — doesn't create separate review processes per regulation, identifies the superset of requirements, and implements the most stringent standard as the baseline with lighter paths for lower-risk code"
+    weight: 0.35
+    description: "Efficient unified compliance framework"
+  - type: llm_judge
+    criteria: "Future-proofing strategy is forward-looking — prepares for the Software Liability Act, supply chain regulations, and AI governance requirements before they take effect, with a regulatory monitoring process that detects new requirements early"
+    weight: 0.30
+    description: "Forward-looking future-proofing"

package/courses/kubernetes-deployment-troubleshooting/course.yaml

@@ -0,0 +1,12 @@
+id: kubernetes-deployment-troubleshooting
+name: "Kubernetes Deployment Troubleshooting"
+description: >
+  Master Kubernetes deployment troubleshooting from pod debugging basics
+  to enterprise platform operations. Learn to diagnose CrashLoopBackOff,
+  ImagePullBackOff, OOMKilled pods, fix networking and service issues,
+  manage storage and RBAC, optimize resources with HPA/VPA, implement
+  GitOps pipelines, and design multi-cluster disaster recovery
+  strategies for large-scale Kubernetes deployments.
+levels: 5
+scenarios_per_level: 10
+tags: [development, Kubernetes, DevOps, troubleshooting, containers, deployment, cloud-native]

package/courses/kubernetes-deployment-troubleshooting/scenarios/level-1/configmap-secret-issues.yaml

@@ -0,0 +1,69 @@
+meta:
+  id: configmap-secret-issues
+  level: 1
+  course: kubernetes-deployment-troubleshooting
+  type: output
+  description: "Debug ConfigMap and Secret issues — diagnose missing environment variables, mount failures, and configuration mismatches"
+  tags: [Kubernetes, ConfigMap, Secret, environment-variables, configuration, beginner]
+
+state: {}
+
+trigger: |
+  Your application deployed successfully but is returning 500 errors.
+  The logs show it can't find its configuration:
+
+  $ kubectl get pods
+  NAME                       READY   STATUS    RESTARTS   AGE
+  auth-svc-2b3c4d5e-fg67   1/1     Running   0          2m
+
+  $ kubectl logs auth-svc-2b3c4d5e-fg67
+  Error: Missing required environment variable: JWT_SECRET
+  Error: Missing required environment variable: REDIS_URL
+  Error: Configuration validation failed, shutting down...
+  Process exited with code 1
+
+  Wait — the pod status shows Running, not CrashLoopBackOff? That's
+  because the container has a startup delay and the crash happened after
+  the liveness probe window.
+
+  $ kubectl describe pod auth-svc-2b3c4d5e-fg67
+  Environment:
+    DATABASE_URL:   <set to the key 'DATABASE_URL' in secret 'auth-secrets'>
+    JWT_SECRET:     <set to the key 'JWT_SECRET' in secret 'auth-secrets'>
+    REDIS_URL:      <set to the key 'REDIS_URL' in configmap 'auth-config'>
+
+  $ kubectl get secret auth-secrets -o jsonpath='{.data}' | jq
+  {
+    "DATABASE_URL": "cG9zdGdyZXM6Ly8uLi4="
+  }
+
+  The secret exists but only has DATABASE_URL — JWT_SECRET is missing
+  from the secret! And the ConfigMap:
+
+  $ kubectl get configmap auth-config
+  Error from server (NotFound): configmaps "auth-config" not found
+
+  The ConfigMap doesn't exist at all. Two issues:
+  1. Secret auth-secrets is missing the JWT_SECRET key
+  2. ConfigMap auth-config was never created
+
+  Task: Explain how ConfigMaps and Secrets work in Kubernetes. Write:
+  how pods consume configuration (env vars vs volume mounts), what
+  happens when a referenced ConfigMap/Secret is missing (pod may or may
+  not start depending on optional flag), how to debug missing config,
+  the difference between ConfigMaps and Secrets, and best practices for
+  configuration management.
+
+assertions:
+  - type: llm_judge
+    criteria: "ConfigMap and Secret consumption is explained — two methods: environment variables (envFrom or env with valueFrom) and volume mounts. envFrom loads all keys, env with valueFrom loads specific keys. Volume mounts project keys as files. If a referenced ConfigMap/Secret doesn't exist, the pod fails to start unless the reference is marked as optional"
+    weight: 0.35
+    description: "ConfigMap/Secret consumption"
+  - type: llm_judge
+    criteria: "Debugging steps are systematic — check pod events (kubectl describe pod), verify ConfigMap/Secret exists (kubectl get cm/secret), inspect keys (kubectl get secret -o jsonpath or -o yaml), verify key names match what the deployment references, check if the reference is in the correct namespace. Shows how base64 encoding works for secrets"
+    weight: 0.35
+    description: "Debugging steps"
+  - type: llm_judge
+    criteria: "Differences and best practices are covered — ConfigMaps for non-sensitive config, Secrets for sensitive data (base64 encoded, can be encrypted at rest in etcd). Best practices: use optional references where appropriate, validate config in CI/CD, use sealed-secrets or external secret managers for production, consider volume mounts for auto-updates vs env vars requiring restart"
+    weight: 0.30
+    description: "Differences and best practices"

package/courses/kubernetes-deployment-troubleshooting/scenarios/level-1/crashloopbackoff.yaml

@@ -0,0 +1,68 @@
+meta:
+  id: crashloopbackoff
+  level: 1
+  course: kubernetes-deployment-troubleshooting
+  type: output
+  description: "Debug CrashLoopBackOff — diagnose why a pod keeps crashing and restarting, using kubectl logs, describe, and events"
+  tags: [Kubernetes, CrashLoopBackOff, debugging, pod-lifecycle, beginner]
+
+state: {}
+
+trigger: |
+  You deployed a new version of your API service and kubectl shows:
+
+  $ kubectl get pods
+  NAME                        READY   STATUS             RESTARTS   AGE
+  api-server-7b8f9c4d-x2k9l  0/1     CrashLoopBackOff   5          3m
+  api-server-7b8f9c4d-m4p7q  0/1     CrashLoopBackOff   5          3m
+  api-server-7b8f9c4d-r9n1j  0/1     CrashLoopBackOff   5          3m
+
+  All 3 replicas are in CrashLoopBackOff. The previous version was
+  running fine. The team is panicking because the API is down.
+
+  kubectl describe pod api-server-7b8f9c4d-x2k9l shows:
+  State:          Waiting
+    Reason:       CrashLoopBackOff
+  Last State:     Terminated
+    Reason:       Error
+    Exit Code:    1
+    Started:      2025-12-01T10:00:05Z
+    Finished:     2025-12-01T10:00:06Z
+
+  Events:
+    Warning  BackOff  3m  kubelet  Back-off restarting failed container
+
+  kubectl logs api-server-7b8f9c4d-x2k9l shows:
+  Error: connect ECONNREFUSED 10.100.50.3:5432
+  Error: Unable to connect to database
+  Process exited with code 1
+
+  The application requires a PostgreSQL database connection. The
+  database is running in the same cluster as a StatefulSet. Nothing
+  changed about the database — only the API image was updated.
+
+  Investigation reveals:
+  - The new image version changed the env var name from DATABASE_URL
+    to DB_CONNECTION_STRING
+  - The ConfigMap still has DATABASE_URL
+  - The container starts, fails to connect (wrong env var), and exits
+
+  Task: Explain how to debug CrashLoopBackOff. Write: what
+  CrashLoopBackOff means (the restart backoff mechanism), the debugging
+  workflow (kubectl logs → describe → events), common causes (app crash,
+  missing env vars, missing dependencies, OOM, wrong command), the fix
+  for this specific case, and how to prevent this in the future.
+
+assertions:
+  - type: llm_judge
+    criteria: "CrashLoopBackOff is explained — the container starts, crashes, Kubernetes restarts it with exponential backoff (10s, 20s, 40s... up to 5 minutes). Exit code 1 indicates application error (not OOMKilled=137, not SIGTERM=143). The backoff means Kubernetes is waiting longer between each restart attempt"
+    weight: 0.35
+    description: "CrashLoopBackOff explained"
+  - type: llm_judge
+    criteria: "Debugging workflow is systematic — (1) kubectl logs <pod> to see application error, (2) kubectl logs <pod> --previous if container already restarted, (3) kubectl describe pod to see events, exit codes, and container state, (4) check env vars with kubectl exec (if pod stays up) or kubectl get cm/secret. Identifies the env var mismatch as root cause"
+    weight: 0.35
+    description: "Systematic debugging workflow"
+  - type: llm_judge
+    criteria: "Fix and prevention are practical — immediate fix: update ConfigMap to include DB_CONNECTION_STRING, or update deployment to map the old var name. Prevention: validate env vars in CI/CD, use health checks (readiness probe on DB connection), and consider using a shared config schema between app versions"
+    weight: 0.30
+    description: "Fix and prevention"

package/courses/kubernetes-deployment-troubleshooting/scenarios/level-1/deployment-rollout.yaml

@@ -0,0 +1,56 @@
+meta:
+  id: deployment-rollout
+  level: 1
+  course: kubernetes-deployment-troubleshooting
+  type: output
+  description: "Debug deployment rollout issues — understand rolling updates, rollback, and why a deployment might get stuck"
+  tags: [Kubernetes, Deployment, rollout, rolling-update, rollback, beginner]
+
+state: {}
+
+trigger: |
+  You updated your deployment to a new image version but the rollout
+  is stuck. Old pods are still running alongside partially updated ones:
+
+  $ kubectl rollout status deployment/user-svc
+  Waiting for deployment "user-svc" spec update to be observed...
+  Waiting for rollout to finish: 1 out of 3 new replicas have been updated...
+
+  $ kubectl get pods
+  NAME                        READY   STATUS             RESTARTS   AGE
+  user-svc-7a8b9c0d-old1    1/1     Running            0          2h
+  user-svc-7a8b9c0d-old2    1/1     Running            0          2h
+  user-svc-7a8b9c0d-old3    1/1     Running            0          2h
+  user-svc-3e4f5g6h-new1    0/1     CrashLoopBackOff   4          5m
+
+  The deployment strategy is RollingUpdate with maxSurge=1 and
+  maxUnavailable=0. The new pod keeps crashing, so the rollout can't
+  proceed (it needs at least 1 new pod Ready before terminating old ones).
+
+  $ kubectl logs user-svc-3e4f5g6h-new1
+  Error: Cannot connect to database — migration v15 not applied
+  The new version requires a database migration that wasn't run.
+
+  The deployment is stuck: new pods crash, old pods keep serving traffic,
+  but the deployment never completes. After 10 minutes the
+  progressDeadlineSeconds (default 600s) will mark it as Failed.
+
+  Task: Explain how Kubernetes deployment rollouts work. Write: the
+  RollingUpdate strategy (maxSurge, maxUnavailable), what happens when
+  a rollout gets stuck, how to check rollout status and history, how
+  to rollback (kubectl rollout undo), progressDeadlineSeconds, and the
+  Recreate strategy as an alternative.
+
+assertions:
+  - type: llm_judge
+    criteria: "Rolling update mechanics are explained — maxSurge controls how many extra pods can be created during update, maxUnavailable controls how many pods can be down. With maxSurge=1 maxUnavailable=0, Kubernetes creates 1 new pod, waits for it to be Ready, then terminates 1 old pod. If the new pod never becomes Ready, the rollout stalls"
+    weight: 0.35
+    description: "Rolling update mechanics"
+  - type: llm_judge
+    criteria: "Stuck rollout debugging is explained — kubectl rollout status shows progress, kubectl rollout history shows revision history, progressDeadlineSeconds (default 600s) marks deployment as Failed if no progress within deadline. A stuck rollout means old pods continue serving traffic (safe but incomplete update)"
+    weight: 0.35
+    description: "Stuck rollout debugging"
+  - type: llm_judge
+    criteria: "Rollback and alternatives are covered — kubectl rollout undo deployment/<name> reverts to previous revision, kubectl rollout undo --to-revision=N reverts to specific version. Recreate strategy: terminates all old pods before creating new ones (causes downtime but avoids version mixing). kubectl rollout pause/resume for controlled rollouts"
+    weight: 0.30
+    description: "Rollback and alternatives"

package/courses/kubernetes-deployment-troubleshooting/scenarios/level-1/first-troubleshooting-shift.yaml

@@ -0,0 +1,65 @@
+meta:
+  id: first-troubleshooting-shift
+  level: 1
+  course: kubernetes-deployment-troubleshooting
+  type: output
+  description: "Combined troubleshooting shift — diagnose multiple pod failures across a namespace using the full beginner debugging toolkit"
+  tags: [Kubernetes, troubleshooting, debugging, combined, shift-simulation, beginner]
+
+state: {}
+
+trigger: |
+  You're on-call and get paged: "Multiple services down in staging
+  namespace." You run:
+
+  $ kubectl get pods -n staging
+  NAME                          READY   STATUS             RESTARTS   AGE
+  api-gw-5a6b7c8d-e9f0        0/1     CrashLoopBackOff   6          15m
+  user-svc-1g2h3i4j-k5l6      0/1     ImagePullBackOff   0          15m
+  order-svc-7m8n9o0p-q1r2     0/1     Pending            0          15m
+  payment-svc-3s4t5u6v-w7x8   1/1     Running            0          15m
+  notification-svc-9a0b-c1d2  0/1     Running            0          15m
+
+  Five services, four different problems:
+
+  1. api-gw — CrashLoopBackOff, exit code 1
+     Logs: "Error: REDIS_HOST environment variable not set"
+     The ConfigMap was deleted during a cleanup.
+
+  2. user-svc — ImagePullBackOff
+     Events: "Failed to pull image 'registry.company.com/user-svc:v3.2.1':
+     unauthorized"
+     The registry token expired overnight.
+
+  3. order-svc — Pending
+     Events: "0/3 nodes are available: 3 Insufficient memory"
+     Requests 4Gi memory but largest available is 2Gi.
+
+  4. payment-svc — Running but 0/1 Ready? No, it shows 1/1, but the
+     Service has no endpoints. Label mismatch: Service selector
+     app=payment, pod label app=payment-svc.
+
+  5. notification-svc — Running, 0/1 Ready
+     Readiness probe failing: HTTP 503 on /ready
+     The downstream email service is unreachable.
+
+  Task: Walk through diagnosing all five issues. Write: the triage
+  approach (start with kubectl get pods, identify status patterns), the
+  debugging steps for each issue type (CrashLoopBackOff → logs,
+  ImagePullBackOff → events, Pending → describe, Service issues →
+  endpoints, Readiness → probe config), and how to prioritize which to
+  fix first in a real incident.
+
+assertions:
+  - type: llm_judge
+    criteria: "All five issues are correctly diagnosed — (1) CrashLoopBackOff from missing ConfigMap causing missing env var, (2) ImagePullBackOff from expired registry credentials, (3) Pending from insufficient memory on nodes, (4) Service-pod label mismatch causing empty endpoints despite pod running, (5) Readiness probe failing due to downstream dependency. Each diagnosis maps to the correct kubectl command"
+    weight: 0.35
+    description: "All issues diagnosed"
+  - type: llm_judge
+    criteria: "Triage methodology is systematic — start with kubectl get pods for overview, group by status type, check most impactful services first. Use kubectl describe for events, kubectl logs for application errors, kubectl get endpoints for service connectivity. Prioritize: fix what unblocks the most services first (e.g., ConfigMap might affect multiple services)"
+    weight: 0.35
+    description: "Triage methodology"
+  - type: llm_judge
+    criteria: "Fixes and prioritization are practical — prioritize payment-svc (revenue-critical, quick label fix), then api-gw (gateway affects all downstream, recreate ConfigMap), then user-svc (refresh registry token), then order-svc (scale down request or add capacity), then notification-svc (investigate downstream dependency). Shows the actual kubectl fix commands"
+    weight: 0.30
+    description: "Fixes and prioritization"

package/courses/kubernetes-deployment-troubleshooting/scenarios/level-1/health-probe-failures.yaml

@@ -0,0 +1,70 @@
+meta:
+  id: health-probe-failures
+  level: 1
+  course: kubernetes-deployment-troubleshooting
+  type: output
+  description: "Debug health probe failures — understand liveness, readiness, and startup probes and why misconfigured probes cause restarts or traffic loss"
+  tags: [Kubernetes, health-probes, liveness, readiness, startup, beginner]
+
+state: {}
+
+trigger: |
+  Your application is running but keeps getting restarted, and users
+  report intermittent 503 errors:
+
+  $ kubectl get pods
+  NAME                       READY   STATUS    RESTARTS   AGE
+  web-app-4a5b6c7d-mn01    1/1     Running   12         1h
+  web-app-4a5b6c7d-op23    0/1     Running   0          30s
+  web-app-4a5b6c7d-qr45    1/1     Running   8          1h
+
+  $ kubectl describe pod web-app-4a5b6c7d-mn01
+  Containers:
+    web-app:
+      Liveness:   http-get http://:8080/healthz delay=5s timeout=1s
+                  period=10s #success=1 #failure=3
+      Readiness:  http-get http://:8080/ready delay=5s timeout=1s
+                  period=10s #success=1 #failure=3
+
+  Events:
+    Warning  Unhealthy  2m   kubelet  Liveness probe failed: HTTP probe
+             failed with statuscode: 503
+    Normal   Killing    2m   kubelet  Container web-app failed liveness
+             check, will be restarted
+    Warning  Unhealthy  30s  kubelet  Readiness probe failed: HTTP probe
+             failed with statuscode: 503
+
+  The application takes 45 seconds to fully start up (loading caches,
+  warming connections). But the liveness probe starts checking at 5
+  seconds with only 3 failures allowed (5s + 3*10s = 35s), so it kills
+  the container before it's ready.
+
+  Additionally, the readiness probe uses the same aggressive timing,
+  so during startup the pod is removed from the Service endpoints,
+  causing 503s for users.
+
+  Problems:
+  1. Liveness probe starts too early — kills the container during startup
+  2. No startup probe — would protect the container during initialization
+  3. Readiness probe timing causes premature endpoint removal
+
+  Task: Explain Kubernetes health probes. Write: the difference between
+  liveness, readiness, and startup probes, what each one controls (restart
+  vs traffic vs startup protection), how to configure timing parameters
+  (initialDelaySeconds, periodSeconds, failureThreshold, timeoutSeconds),
+  common misconfiguration patterns, and best practices for slow-starting
+  applications.
+
+assertions:
+  - type: llm_judge
+    criteria: "All three probe types are explained — liveness: kills and restarts the container if it fails (detects deadlocks/hangs), readiness: removes pod from Service endpoints if it fails (controls traffic routing), startup: disables liveness/readiness until it succeeds (protects slow-starting containers). Each probe serves a different purpose and should not use the same endpoint"
+    weight: 0.35
+    description: "Probe types explained"
+  - type: llm_judge
+    criteria: "Timing parameters are explained with the math — initialDelaySeconds (wait before first check), periodSeconds (interval between checks), failureThreshold (consecutive failures before action), timeoutSeconds (per-check timeout). Total startup tolerance = initialDelaySeconds + (failureThreshold * periodSeconds). In this case: 5 + (3*10) = 35s < 45s startup time, so the container gets killed"
+    weight: 0.35
+    description: "Timing parameters explained"
+  - type: llm_judge
+    criteria: "Fix and best practices are practical — add a startup probe with generous timeout (e.g., failureThreshold=30, periodSeconds=5 = 150s window), keep liveness probe for runtime health only (not startup), make readiness check actual dependency availability, never use the same endpoint for all three probes if they serve different purposes"
+    weight: 0.30
+    description: "Fix and best practices"