dojo.md 0.1.0 → 0.2.0

package/courses/github-pr-review/scenarios/level-2/cross-team-review.yaml

@@ -0,0 +1,61 @@
+meta:
+  id: cross-team-review
+  level: 2
+  course: github-pr-review
+  type: output
+  description: "Cross-team code review — review PRs outside your domain expertise, ask effective questions, and provide value without deep context"
+  tags: [github, pr-review, cross-team, knowledge-sharing, communication, intermediate]
+
+state: {}
+
+trigger: |
+  You're a frontend engineer asked to review 3 PRs from teams outside
+  your usual domain. You need to provide valuable feedback despite not
+  being a domain expert.
+
+  PR #401 — From the Data team: "Add real-time analytics pipeline"
+  You don't know Kafka or Spark, but the PR touches shared API contracts
+  your frontend consumes. Changes include:
+  - New event schema for user interactions (affects your tracking code)
+  - API response format change for the analytics dashboard endpoint
+  - New WebSocket endpoint for real-time data
+  The PR has 400 lines, good tests, but the API changes aren't
+  documented and the response format breaks backward compatibility.
+
+  PR #402 — From the Infrastructure team: "Migrate to Kubernetes"
+  You don't know K8s well, but the PR modifies environment variables and
+  deployment configuration that affect your app. Changes include:
+  - New environment variable naming convention (REACT_APP_ → NEXT_PUBLIC_)
+  - Health check endpoint added (your app needs to implement /healthz)
+  - Changed base URL configuration from hardcoded to dynamic
+  The PR is 600 lines of YAML and config, with a migration guide buried
+  in a comment.
+
+  PR #403 — From the Mobile team: "Add shared component library"
+  The mobile team is creating a shared React Native component library
+  that should share design tokens with your web components. Changes:
+  - New design token format (different from your current CSS variables)
+  - Shared TypeScript types for API responses
+  - A utility function that duplicates logic from your web codebase
+  The PR is 250 lines with no mention of the web team in the description.
+
+  Task: Review all 3 PRs. For each, write: what you can and can't
+  evaluate as a non-domain expert, the specific feedback you can provide
+  (API contracts, compatibility, shared code), the questions to ask the
+  authors (framed constructively, not "I don't understand"), and the
+  cross-team concerns to raise. Include a meta-analysis of what this
+  cross-team review experience reveals about organizational communication.
+
+assertions:
+  - type: llm_judge
+    criteria: "Reviews add value despite limited domain knowledge — identifies API contract breaks in #401, environment variable migration risks in #402, and code duplication in #403, all from the frontend perspective without pretending to understand Kafka/K8s internals"
+    weight: 0.35
+    description: "Value-adding cross-team reviews"
+  - type: llm_judge
+    criteria: "Questions are constructive and specific — asks about backward compatibility plans (not 'will this break things?'), migration timeline for env vars, and design token unification strategy, showing respect for the authors' domain expertise"
+    weight: 0.35
+    description: "Constructive cross-team questions"
+  - type: llm_judge
+    criteria: "Organizational patterns are identified — notes that cross-team PRs need better API change documentation, shared code should have cross-team visibility, and suggests process improvements (RFC for cross-team changes, shared API contract tests)"
+    weight: 0.30
+    description: "Organizational pattern recognition"

package/courses/github-pr-review/scenarios/level-2/intermediate-review-shift.yaml

@@ -0,0 +1,66 @@
+meta:
+  id: intermediate-review-shift
+  level: 2
+  course: github-pr-review
+  type: output
+  description: "Intermediate review shift — handle a complex batch of PRs requiring security, performance, and cross-team review skills"
+  tags: [github, pr-review, shift-simulation, batch-review, intermediate]
+
+state: {}
+
+trigger: |
+  You're doing a review shift with 4 challenging PRs. Each requires
+  different intermediate skills.
+
+  PR #501 (critical, 2 hours old): "Hotfix: Rate limit the signup
+  endpoint"
+  Author: On-call engineer. Context: The signup endpoint is being
+  abused — 10,000 fake accounts created in the last hour. The fix adds
+  Redis-based rate limiting: 5 signups per IP per hour.
+  Code concern: The rate limit key is based only on IP address (easily
+  bypassed with proxies), the Redis connection has no error handling (if
+  Redis is down, all signups fail), and the rate limit response doesn't
+  include Retry-After header.
+  Urgency: Active abuse happening now.
+
+  PR #502 (medium, 1 day old): "Add real-time notifications via SSE"
+  Author: Mid-level engineer. 350 lines adding Server-Sent Events for
+  notification delivery. The implementation keeps all SSE connections in
+  a Map in memory, with no connection limit, no heartbeat, and no
+  cleanup of dead connections. In production with 50K concurrent users,
+  this would exhaust memory.
+  Tests: Only tests the happy path with 1 connection.
+
+  PR #503 (low urgency, 3 days old): "Migrate from Moment.js to
+  date-fns"
+  Author: Junior engineer. 800 lines of date library migration. Most
+  changes are mechanical (moment().format() → format(new Date())), but
+  3 timezone conversions are incorrect — they use local timezone instead
+  of UTC, which would break for users in non-UTC timezones.
+  CI: Green (tests don't cover timezone edge cases).
+
+  PR #504 (medium, 4 hours old): "Stacked PR 2/3: Add payment webhooks"
+  This is the second PR in a 3-PR stack. PR 1/3 (payment model) was
+  merged with a review comment about adding an index that was never
+  addressed. This PR adds webhook handling but references the unindexed
+  column in queries that will be called for every webhook event.
+
+  Task: Review all 4 PRs. For each, write: the priority order with
+  justification, a focused review addressing the key technical concern,
+  the decision (approve/request changes/comment) with rationale, and
+  specific code-level feedback. End with a shift summary noting patterns
+  and team-level observations.
+
+assertions:
+  - type: llm_judge
+    criteria: "Priority order balances urgency with risk — PR #501 is first (active abuse), but the review still catches security gaps in the rate limit implementation rather than rubber-stamping the hotfix. The stacked PR #504 gets attention for the carried-over tech debt"
+    weight: 0.35
+    description: "Urgency-balanced priority order"
+  - type: llm_judge
+    criteria: "Technical depth is appropriate per PR — #501 gets security-focused review (rate limit bypass, Redis failure mode), #502 gets scalability review (memory exhaustion, connection management), #503 catches timezone bugs, #504 addresses the unresolved index issue from the previous PR"
+    weight: 0.35
+    description: "Appropriate technical depth"
+  - type: llm_judge
+    criteria: "Shift summary identifies systemic issues — notes patterns across PRs (missing error handling, insufficient test coverage for edge cases, tech debt carried across stacked PRs) and recommends team-level improvements"
+    weight: 0.30
+    description: "Systemic issue identification"

package/courses/github-pr-review/scenarios/level-2/performance-review-patterns.yaml

@@ -0,0 +1,99 @@
+meta:
+  id: performance-review-patterns
+  level: 2
+  course: github-pr-review
+  type: output
+  description: "Performance-focused code review — identify N+1 queries, memory leaks, and inefficient patterns in pull requests"
+  tags: [github, pr-review, performance, N+1, memory-leaks, intermediate]
+
+state: {}
+
+trigger: |
+  You're reviewing a PR titled "Add order history page with product
+  details." The PR loads a user's order history and displays product
+  information. Review these code sections for performance issues:
+
+  Section 1 — API endpoint:
+  ```javascript
+  app.get('/api/orders', async (req, res) => {
+    const orders = await Order.findAll({ where: { userId: req.user.id } });
+    const result = [];
+    for (const order of orders) {
+      const items = await OrderItem.findAll({ where: { orderId: order.id } });
+      for (const item of items) {
+        item.product = await Product.findOne({ where: { id: item.productId } });
+        item.reviews = await Review.findAll({ where: { productId: item.productId } });
+      }
+      result.push({ ...order.toJSON(), items });
+    }
+    res.json(result);
+  });
+  ```
+
+  Section 2 — React component:
+  ```jsx
+  function OrderHistory() {
+    const [orders, setOrders] = useState([]);
+    const [enrichedOrders, setEnrichedOrders] = useState([]);
+
+    useEffect(() => {
+      fetch('/api/orders').then(r => r.json()).then(setOrders);
+    }, []);
+
+    useEffect(() => {
+      orders.forEach(async (order) => {
+        const shipping = await fetch(`/api/shipping/${order.id}`).then(r => r.json());
+        setEnrichedOrders(prev => [...prev, { ...order, shipping }]);
+      });
+    }, [orders]);
+
+    return (
+      <div>
+        {enrichedOrders.map(order => (
+          <OrderCard key={order.id} order={order} />
+        ))}
+      </div>
+    );
+  }
+  ```
+
+  Section 3 — Utility function:
+  ```javascript
+  function formatOrdersForExport(orders) {
+    const allProducts = [];
+    orders.forEach(order => {
+      order.items.forEach(item => {
+        allProducts.push(JSON.parse(JSON.stringify(item.product)));
+      });
+    });
+    return allProducts.map(p => ({
+      ...p,
+      formattedPrice: new Intl.NumberFormat('en-US', {
+        style: 'currency', currency: 'USD'
+      }).format(p.price)
+    }));
+  }
+  ```
+
+  The user has 50 orders on average, each with 3-5 items. The page
+  currently takes 8 seconds to load.
+
+  Task: Write a performance-focused review. For each section: name the
+  performance anti-pattern, estimate the impact (number of queries,
+  memory usage, render cycles), provide the optimized solution with code,
+  and explain why the optimization works. Include a summary of expected
+  performance improvement.
+
+assertions:
+  - type: llm_judge
+    criteria: "N+1 query problem is identified and fixed — Section 1 has nested N+1 queries (orders → items → products → reviews), and the fix uses eager loading (includes/joins) or batch queries to reduce from O(n*m) queries to O(1) or O(k)"
+    weight: 0.35
+    description: "N+1 query identification and fix"
+  - type: llm_judge
+    criteria: "Frontend performance issues are identified — Section 2 causes waterfall API calls (one per order), causes re-renders on every setState in the loop, and has a race condition with the enrichedOrders accumulation. Fix uses Promise.all or batched endpoint"
+    weight: 0.35
+    description: "Frontend performance issues"
+  - type: llm_judge
+    criteria: "Memory and computation waste identified — Section 3 deep-clones objects unnecessarily with JSON.parse/JSON.stringify, creates a new Intl.NumberFormat for each item instead of reusing it, and the fixes show proper optimization with minimal memory allocation"
+    weight: 0.30
+    description: "Memory and computation optimization"

package/courses/github-pr-review/scenarios/level-2/review-disagreement-resolution.yaml

@@ -0,0 +1,64 @@
+meta:
+  id: review-disagreement-resolution
+  level: 2
+  course: github-pr-review
+  type: output
+  description: "Resolve review disagreements — handle conflicting reviewer opinions, technical disputes, and author pushback constructively"
+  tags: [github, pr-review, conflict-resolution, disagreement, communication, intermediate]
+
+state: {}
+
+trigger: |
+  You're a senior engineer mediating review disagreements on 3 PRs
+  where reviewers and authors have reached an impasse.
+
+  Dispute #1 — Architecture disagreement:
+  PR "Refactor user service to microservice" has been open for 2 weeks.
+  - Author (mid-level): Extracted the user service into a separate
+    microservice with its own database. Says it improves scalability.
+  - Reviewer A (staff engineer): "This adds unnecessary complexity.
+    We're a 10-person team. Keep it as a module in the monolith."
+  - Reviewer B (senior): "I agree with the extraction but the API
+    contract is wrong — it should use gRPC, not REST."
+  - Author: "I've already spent 3 weeks on this. I'm not rewriting it."
+  Both reviewers have valid points. The PR has 1,500 lines changed.
+
+  Dispute #2 — Style/preference war:
+  PR "Add error handling to checkout flow" has 47 review comments.
+  - Reviewer keeps requesting changes for style preferences not in the
+    style guide: single quotes vs double quotes, trailing commas,
+    function declarations vs arrow functions.
+  - Author: "These are personal preferences, not bugs. Our style guide
+    doesn't cover this. I'm not changing them."
+  - The actual error handling logic hasn't been reviewed at all.
+
+  Dispute #3 — Testing philosophy clash:
+  PR "Add payment retry logic" has 2 reviewers disagreeing:
+  - Reviewer A: "These tests mock too much. They don't test real
+    behavior. Write integration tests."
+  - Reviewer B: "Integration tests are slow and flaky. Unit tests with
+    mocks are the right approach. Ship it."
+  - Author: "I wrote what Reviewer B asked for last time. Now Reviewer A
+    wants something different. Which is it?"
+  The team has no documented testing strategy.
+
+  Task: For each dispute, write: the root cause of the disagreement
+  (technical, process, or interpersonal), the mediation approach (how
+  to move forward without picking sides), the specific resolution with
+  rationale, the process improvement to prevent recurrence, and the
+  actual review comments you would post. Include a summary of when to
+  escalate vs mediate.
+
+assertions:
+  - type: llm_judge
+    criteria: "Root causes are correctly diagnosed — Dispute #1 is a scope/architecture issue (PR too large, decision should have been made before coding), #2 is a process issue (style guide gaps), #3 is a documentation/alignment issue (no testing strategy)"
+    weight: 0.35
+    description: "Correct root cause diagnosis"
+  - type: llm_judge
+    criteria: "Resolutions are practical and fair — doesn't just pick a side, suggests concrete paths forward (e.g., for #1: scope down to module extraction without separate service, for #2: end the style war and focus on the error handling, for #3: define testing strategy then apply)"
+    weight: 0.35
+    description: "Practical and fair resolutions"
+  - type: llm_judge
+    criteria: "Process improvements prevent recurrence — suggests architectural decision records (ADRs) for #1, style guide expansion and linter rules for #2, documented testing strategy for #3, and general guidelines for when reviewers disagree"
+    weight: 0.30
+    description: "Recurrence-preventing process improvements"

package/courses/github-pr-review/scenarios/level-2/review-metrics-analysis.yaml

@@ -0,0 +1,63 @@
+meta:
+  id: review-metrics-analysis
+  level: 2
+  course: github-pr-review
+  type: output
+  description: "Analyze review metrics — interpret PR review data to identify bottlenecks, improve turnaround time, and balance reviewer load"
+  tags: [github, pr-review, metrics, analytics, turnaround-time, intermediate]
+
+state: {}
+
+trigger: |
+  You're a team lead analyzing 3 months of PR review data for your
+  12-person engineering team. Management is concerned about shipping
+  velocity. Here's the data:
+
+  Overall metrics:
+  - Average time to first review: 18 hours
+  - Average time to merge: 4.2 days
+  - Average review rounds: 2.8
+  - PRs merged per week: 23
+  - PRs abandoned/closed without merge: 8 per week
+
+  Per-reviewer breakdown:
+  | Reviewer | Reviews/week | Avg first review (hrs) | Avg comments | Approval rate |
+  |----------|-------------|----------------------|--------------|---------------|
+  | Alice    | 14          | 4                    | 8.2          | 35%           |
+  | Bob      | 12          | 6                    | 3.1          | 72%           |
+  | Carol    | 3           | 48                   | 1.5          | 90%           |
+  | David    | 8           | 12                   | 5.4          | 55%           |
+  | Eve      | 2           | 72                   | 0.8          | 95%           |
+  | Frank    | 6           | 24                   | 4.7          | 60%           |
+
+  PR size distribution:
+  - Under 100 lines: 30% (avg 1.2 days to merge)
+  - 100-400 lines: 45% (avg 3.8 days to merge)
+  - 400+ lines: 25% (avg 8.5 days to merge)
+
+  Common review comment categories:
+  - Style/formatting: 35%
+  - Logic errors: 20%
+  - Missing tests: 18%
+  - Architecture concerns: 15%
+  - Documentation: 12%
+
+  Task: Analyze the data and write: the key findings (what's working,
+  what's not), the root causes behind slow merge times, specific
+  recommendations for each bottleneck (reviewer load balancing, PR size
+  policy, automation opportunities), an action plan with expected impact,
+  and the dashboard design for ongoing monitoring.
+
+assertions:
+  - type: llm_judge
+    criteria: "Key bottlenecks are identified — Alice is a bottleneck (too many reviews, too critical), Carol and Eve are under-reviewing, 35% of comments are style issues that should be automated, large PRs take disproportionately long, and the abandonment rate is high"
+    weight: 0.35
+    description: "Bottleneck identification"
+  - type: llm_judge
+    criteria: "Recommendations are specific and actionable — includes reviewer load rebalancing (cap Alice, increase Carol/Eve), automating style checks to eliminate 35% of comments, enforcing PR size limits, and reducing review rounds through better PR descriptions"
+    weight: 0.35
+    description: "Specific recommendations"
+  - type: llm_judge
+    criteria: "Action plan includes expected impact — quantifies improvements (e.g., automating style saves X hours/week, rebalancing reduces first-review time by Y hours), prioritizes actions by impact, and the dashboard tracks leading indicators not just lagging metrics"
+    weight: 0.30
+    description: "Quantified action plan"

package/courses/github-pr-review/scenarios/level-2/review-turnaround-sla.yaml

@@ -0,0 +1,54 @@
+meta:
+  id: review-turnaround-sla
+  level: 2
+  course: github-pr-review
+  type: output
+  description: "Design review SLAs — create turnaround time agreements that balance speed with quality and handle escalations"
+  tags: [github, pr-review, SLA, turnaround-time, process, intermediate]
+
+state: {}
+
+trigger: |
+  Your engineering org (40 developers, 4 teams) has no formal review
+  SLAs. The result: some PRs get reviewed in minutes (if the author
+  pings on Slack), others sit for days (if the author is quiet). This
+  creates frustration and slows delivery unpredictably.
+
+  Current pain points:
+  - Average first-review time varies wildly: 1 hour to 5 days
+  - Hotfixes sometimes wait behind feature PRs
+  - Junior engineers' PRs wait longer than senior engineers' PRs
+  - Cross-team reviews are the slowest (2x longer than within-team)
+  - No escalation path when a review is stuck
+  - Some reviewers batch all reviews to Friday afternoon
+  - No distinction between "quick look" reviews and deep reviews
+
+  Team composition:
+  - Platform team (8 devs): infrastructure, shared libraries
+  - Product team A (12 devs): user-facing features
+  - Product team B (10 devs): merchant-facing features
+  - Data team (10 devs): pipelines, analytics, ML
+
+  Task: Design the review SLA framework. Write: the SLA tiers (by PR
+  type, size, and urgency — with specific time targets for first review
+  and final decision), the escalation process (what happens when SLA is
+  missed — auto-assign, manager notification, etc.), the cross-team
+  review protocol (how to handle reviews that need expertise from another
+  team), the GitHub automation to track and enforce SLAs (labels, bots,
+  notifications), and the fairness mechanisms (ensuring junior engineers
+  get timely reviews, preventing reviewer burnout). Include the rollout
+  communication plan.
+
+assertions:
+  - type: llm_judge
+    criteria: "SLA tiers are well-designed — differentiates by urgency (hotfix < 2 hrs, normal < 1 business day, large/architectural < 2 days), by size (small PRs get faster targets), and includes separate targets for first review vs final decision"
+    weight: 0.35
+    description: "Well-designed SLA tiers"
+  - type: llm_judge
+    criteria: "Escalation and automation are practical — includes graduated escalation (reminder → reassign → manager), GitHub Actions or bot configuration for SLA tracking, label-based routing, and doesn't create notification fatigue"
+    weight: 0.35
+    description: "Practical escalation and automation"
+  - type: llm_judge
+    criteria: "Fairness and sustainability are addressed — prevents reviewer burnout (review load caps, rotation), ensures junior engineers' PRs don't get deprioritized, handles cross-team reviews with designated liaisons, and the communication plan gets buy-in"
+    weight: 0.30
+    description: "Fair and sustainable framework"

package/courses/github-pr-review/scenarios/level-2/stacked-pr-review.yaml

@@ -0,0 +1,65 @@
+meta:
+  id: stacked-pr-review
+  level: 2
+  course: github-pr-review
+  type: output
+  description: "Review stacked PRs — handle dependent PR chains, manage merge order, and review incremental changes effectively"
+  tags: [github, pr-review, stacked-prs, dependencies, workflow, intermediate]
+
+state: {}
+
+trigger: |
+  A senior engineer has submitted a stack of 4 dependent PRs for a
+  payment processing feature. They've asked you to review the full
+  stack. The PRs must be merged in order.
+
+  PR #301 (base: main) — "Add Payment model and database migration"
+  - 120 lines: new Payment table, migration, model with validations
+  - Status: CI green, no other reviews yet
+  - The migration adds columns: amount, currency, status, stripe_id,
+    created_at, updated_at
+  - You notice: no index on stripe_id, status enum uses strings instead
+    of an integer enum, no soft delete support
+
+  PR #302 (base: PR #301) — "Add payment processing service"
+  - 200 lines: PaymentService class, Stripe integration, error handling
+  - Status: CI green (includes #301's changes)
+  - Handles: create, capture, refund, webhook processing
+  - You notice: good error handling, but the refund method doesn't
+    check if the payment was already refunded, and the webhook handler
+    doesn't validate the Stripe signature
+
+  PR #303 (base: PR #302) — "Add payment API endpoints"
+  - 150 lines: REST endpoints, request validation, authentication
+  - Status: CI green
+  - You notice: endpoints look good, but there's no rate limiting on
+    the create-payment endpoint, and error responses leak internal
+    error messages to the client
+
+  PR #304 (base: PR #303) — "Add payment UI components"
+  - 180 lines: React components, form validation, loading states
+  - Status: CI green
+  - You notice: good UX, but the payment form doesn't disable the
+    submit button after click (double-charge risk), and there's no
+    idempotency key sent with the request
+
+  Task: Review the full stack. Write: the review strategy (how to
+  approach reviewing dependent PRs — top-down vs bottom-up, what to
+  focus on at each layer), the review for each PR (noting which issues
+  block the entire stack vs just that PR), the guidance on which issues
+  to fix before merging vs address in follow-ups, and the merge plan
+  (order, timing, what to verify between merges).
+
+assertions:
+  - type: llm_judge
+    criteria: "Review strategy is sound — reviews bottom-up (data layer first), identifies which issues are stack-blocking (migration issues in #301 block everything) vs local (UI issues in #304 only affect that PR), and reviews each PR in the context of the full feature"
+    weight: 0.35
+    description: "Sound stacked PR review strategy"
+  - type: llm_judge
+    criteria: "Issues are correctly categorized — missing stripe_id index and webhook signature validation are blocking issues, double-submit in UI is important but could be a follow-up, and the review recognizes that some issues span PRs (idempotency needs both API and UI changes)"
+    weight: 0.35
+    description: "Correct issue categorization"
+  - type: llm_judge
+    criteria: "Merge plan is practical — addresses the risks of merging a stack (what happens if #301 merges but #302 needs changes), suggests rebasing strategy, and handles the case where a middle PR needs significant changes"
+    weight: 0.30
+    description: "Practical merge plan"

package/courses/github-pr-review/scenarios/level-3/advanced-review-shift.yaml

@@ -0,0 +1,65 @@
+meta:
+  id: advanced-review-shift
+  level: 3
+  course: github-pr-review
+  type: output
+  description: "Advanced review shift — handle cross-functional reviews, compliance requirements, and process improvements simultaneously"
+  tags: [github, pr-review, shift-simulation, cross-functional, compliance, advanced]
+
+state: {}
+
+trigger: |
+  You're the review lead for the week. Your shift involves complex
+  reviews that span organizational boundaries and require process-level
+  decisions.
+
+  Situation 1 — Compliance-critical PR:
+  PR #601: "Add PCI DSS logging to payment endpoints" (180 lines)
+  The PR adds audit logging but the implementation logs full credit card
+  numbers in the "debug" log level. The author says debug logs are "only
+  for development" but you know they're enabled in staging which shares
+  infrastructure with production logs. This PR is blocking a PCI audit
+  next week.
+  Two reviewers have already approved it.
+
+  Situation 2 — Cross-team architecture dispute:
+  PR #602: "Shared authentication library v2" (450 lines)
+  The platform team submitted a breaking change to the auth library.
+  Three consuming teams have pushed back in the PR comments — 87
+  comments over 5 days with no resolution. The backend team wants OAuth,
+  the mobile team wants JWT, and the frontend team wants session-based.
+  The platform team is frustrated and threatening to merge without
+  consensus.
+
+  Situation 3 — Review process failure:
+  A production incident occurred because a PR was merged with a stale
+  approval — the code changed significantly after the approval, but
+  GitHub didn't require re-review. The CTO wants a fix before end of
+  week.
+
+  Situation 4 — Culture challenge:
+  A junior engineer comes to you privately saying a senior reviewer has
+  been leaving dismissive comments like "this is obviously wrong" and
+  "any competent developer would know this." The junior wants to change
+  teams. You check the PR history and confirm the pattern — 15 PRs with
+  similar comments in the last month.
+
+  Task: Handle all 4 situations. For each, write: the immediate action
+  (what to do right now), the resolution (how to resolve the core issue),
+  the process improvement (how to prevent recurrence), and the
+  communication (what to say and to whom). Include a weekly review lead
+  summary for the engineering leadership.
+
+assertions:
+  - type: llm_judge
+    criteria: "Compliance situation is handled correctly — the PCI logging issue is flagged as a blocker despite 2 existing approvals, the approval is dismissed/review requested, and the fix addresses the credit card logging in all environments, not just production"
+    weight: 0.35
+    description: "Correct compliance handling"
+  - type: llm_judge
+    criteria: "Architecture dispute is resolved constructively — doesn't pick a side in the PR, escalates to an architectural decision record (ADR) or RFC process, proposes an in-person/sync discussion, and addresses the platform team's frustration with a timeline commitment"
+    weight: 0.35
+    description: "Constructive dispute resolution"
+  - type: llm_judge
+    criteria: "Culture issue is addressed seriously — the senior reviewer's behavior is addressed through management (not publicly in PRs), the junior engineer is supported, and the systemic fix includes reviewer conduct expectations and a feedback mechanism"
+    weight: 0.30
+    description: "Serious culture issue handling"

package/courses/github-pr-review/scenarios/level-3/ai-powered-review.yaml

@@ -0,0 +1,58 @@
+meta:
+  id: ai-powered-review
+  level: 3
+  course: github-pr-review
+  type: output
+  description: "Implement AI-powered code review — evaluate and integrate AI review tools, define human-AI review boundaries, and measure effectiveness"
+  tags: [github, pr-review, AI, automation, LLM, code-analysis, advanced]
+
+state: {}
+
+trigger: |
+  Your CTO wants to adopt AI-powered code review to reduce review
+  bottlenecks. You've been tasked with evaluating the approach and
+  designing the integration. Your team has 80 engineers across 25 repos.
+
+  Tools to evaluate:
+  1. GitHub Copilot code review (built-in, understands repo context)
+  2. CodeRabbit (AI review bot, posts inline comments)
+  3. Sourcery (automated refactoring suggestions)
+  4. Custom solution using Claude/GPT API with GitHub webhooks
+
+  Current review data:
+  - 120 PRs per week, average 4 review comments each
+  - Comment breakdown: 40% style/formatting, 25% bug/logic, 20%
+    performance, 15% architecture
+  - Average reviewer time per PR: 25 minutes
+  - 60% of first-round comments are issues AI could catch
+
+  Concerns from the team:
+  - "AI reviews will be noisy and developers will start ignoring all
+    automated feedback"
+  - "We'll lose the learning aspect of human review"
+  - "Who's responsible when AI misses a bug that a human would catch?"
+  - "AI can't understand our business domain and conventions"
+  - "Junior engineers will stop learning if AI does the reviewing"
+
+  Task: Design the AI review integration. Write: the tool evaluation
+  matrix (features, accuracy, cost, integration complexity for each),
+  the human-AI boundary definition (what AI reviews vs what humans
+  review), the integration architecture (GitHub Actions workflow, comment
+  formatting, noise reduction), the measurement framework (how to track
+  AI review accuracy, false positive rate, developer satisfaction), and
+  the change management plan (addressing team concerns, pilot program,
+  rollout). Include cost-benefit analysis.
+
+assertions:
+  - type: llm_judge
+    criteria: "Tool evaluation is thorough — compares all 4 options on accuracy, cost, integration effort, and noise level, with a clear recommendation and reasoning. Considers the custom solution's flexibility vs maintenance burden"
+    weight: 0.35
+    description: "Thorough tool evaluation"
+  - type: llm_judge
+    criteria: "Human-AI boundaries are well-defined — AI handles style/formatting (40% of comments), flags potential bugs for human verification, and humans focus on architecture/design/domain logic. Addresses the learning concern by keeping educational review interactions human"
+    weight: 0.35
+    description: "Well-defined human-AI boundaries"
+  - type: llm_judge
+    criteria: "Change management addresses real concerns — the pilot program starts small and measures before scaling, noise reduction strategy prevents alert fatigue, the cost-benefit analysis quantifies saved reviewer hours vs tool cost, and the plan includes an exit strategy"
+    weight: 0.30
+    description: "Realistic change management"

package/courses/github-pr-review/scenarios/level-3/compliance-review-process.yaml

@@ -0,0 +1,64 @@
+meta:
+  id: compliance-review-process
+  level: 3
+  course: github-pr-review
+  type: output
+  description: "Design compliance-aware review — build review processes that satisfy SOX, SOC 2, HIPAA, and PCI DSS audit requirements"
+  tags: [github, pr-review, compliance, SOX, SOC2, audit, advanced]
+
+state: {}
+
+trigger: |
+  Your fintech company is preparing for SOC 2 Type II and PCI DSS
+  audits. The auditors will examine your code review process as part
+  of change management controls. Currently your process has gaps that
+  would fail the audit.
+
+  Audit requirements:
+  1. SOC 2 — Change Management (CC8.1):
+     - All production changes must be reviewed by someone other than
+       the author
+     - Reviews must be documented and traceable
+     - Emergency changes must have post-deployment review within 24 hrs
+     - Separation of duties: developer cannot approve and deploy
+
+  2. PCI DSS — Requirement 6.5:
+     - Code reviews must check for OWASP Top 10 vulnerabilities
+     - Security-focused review must be documented
+     - All custom code changes in the cardholder data environment must
+       be reviewed before deployment
+
+  3. SOX (if applicable to financial reporting code):
+     - Changes to financial calculation code require dual approval
+     - Complete audit trail of who reviewed, when, and what was decided
+
+  Current gaps:
+  - 15% of PRs are merged by the author (self-merge after auto-approve
+    from CI)
+  - No documented security review checklist
+  - Emergency hotfixes bypass review entirely
+  - No separation between code approval and deployment
+  - Review comments are sometimes deleted or edited after merge
+  - No way to prove a human reviewed the code (vs rubber stamp)
+
+  Task: Design the compliance-aware review process. Write: the branch
+  protection rules that enforce separation of duties, the security
+  review checklist (OWASP-focused, documented per PR), the emergency
+  change process (fast but auditable), the audit trail requirements
+  (what to log, how to preserve, how to present to auditors), and the
+  GitHub configuration (rulesets, required reviews, CODEOWNERS for
+  sensitive code paths). Include sample audit evidence you would present.
+
+assertions:
+  - type: llm_judge
+    criteria: "Compliance controls are complete — prevents self-merge (branch protection), requires documented security review for PCI-scoped code, enforces dual approval for SOX-scope financial code, and creates an immutable audit trail"
+    weight: 0.35
+    description: "Complete compliance controls"
+  - type: llm_judge
+    criteria: "Emergency process balances speed with compliance — allows expedited merges with reduced (but not zero) review requirements, mandates post-deployment review within 24 hours, and creates an audit trail even for emergency changes"
+    weight: 0.35
+    description: "Balanced emergency process"
+  - type: llm_judge
+    criteria: "Audit evidence is convincing — includes sample reports, GitHub configurations that create tamper-proof trails, and the process for presenting review history to auditors. Addresses the gap of edited/deleted review comments"
+    weight: 0.30
+    description: "Convincing audit evidence"