dojo.md 0.2.3 → 0.2.4

package/courses/code-review-feedback-writing/scenarios/level-5/review-velocity-impact.yaml

@@ -0,0 +1,44 @@
+meta:
+  id: review-velocity-impact
+  level: 5
+  course: code-review-feedback-writing
+  type: output
+  description: "Analyze review impact on velocity — quantify how code review practices affect engineering team velocity, quality, and delivery predictability"
+  tags: [code-review, velocity, engineering-metrics, delivery, impact-analysis, master]
+
+state: {}
+
+trigger: |
+  The CEO asks: "Code review takes 30% of our engineering time. Is it
+  worth it? Should we reduce review requirements to ship faster?"
+
+  Data available:
+  - Engineering time: 30% of developer hours spent on review activities
+  - Cycle time: average 7 days from PR open to production (review is
+    4 of those 7 days)
+  - Defect rate: teams with thorough reviews have 3x fewer production bugs
+  - But: teams with fastest reviews ship 2x more features per quarter
+  - Developer satisfaction: inversely correlated with review wait time
+  - Knowledge sharing: 60% of cross-team knowledge transfer happens
+    through code reviews
+  - Onboarding: new engineers who receive detailed reviews reach full
+    productivity 40% faster
+
+  Task: Write the analysis for the CEO. Include: the true cost of
+  code review, the true cost of NOT reviewing, optimization
+  opportunities (maintain quality, reduce time), and a recommendation
+  with projected impact. Use data to tell the story.
+
+assertions:
+  - type: llm_judge
+    criteria: "Cost analysis is honest and complete — cost of review: 30% of engineering time = $X million/year (calculate from team size and average salary). 4 of 7 days in cycle time is a bottleneck. Opportunity cost: features not shipped during review wait time. Cost of NOT reviewing: 3x more production bugs × average bug fix cost ($5K-50K each) = $Y million/year in bug costs. Knowledge silos: without reviews, knowledge stays in individual heads (bus factor risk). Onboarding: 40% slower onboarding = $Z additional cost per new hire. Comparison: review investment should be compared to the alternative (more bugs, slower onboarding, knowledge loss), not to zero. Key insight: 'The question isn't whether to do reviews — it's whether we're doing them efficiently.'"
+    weight: 0.35
+    description: "Cost analysis"
+  - type: llm_judge
+    criteria: "Optimization recommendations maintain quality while reducing time — 'We can reduce review time from 4 days to 1.5 days without reducing quality.' Specific interventions: (1) Automate style/formatting (saves 40% of review time — Prettier, ESLint). (2) PR size limits (smaller PRs reviewed faster — 200 vs 500 lines saves 2-3 hours per review). (3) Reviewer assignment automation (eliminates 1-2 day assignment delay). (4) Review SLA (24-hour first review commitment). (5) High-quality first submissions (PR templates, self-review checklist reduce review rounds). Projected impact: review time from 30% to 20% of engineering hours, cycle time from 7 to 4 days, feature delivery +30%, quality maintained or improved. Each recommendation with expected time savings and implementation cost"
+    weight: 0.35
+    description: "Optimization plan"
+  - type: llm_judge
+    criteria: "Recommendation is data-driven and CEO-friendly — framing: 'Code review is engineering infrastructure — like CI/CD or monitoring. The question isn't whether to invest, but how to invest efficiently.' Recommendation: optimize, don't reduce. Reducing review thoroughness has compounding costs: bugs cost 10x more to fix in production than in review, knowledge loss is irreversible, onboarding slows permanently. Projected outcomes: invest $50K in automation + 90-day process improvement → save $200K/year in review time + $150K/year in prevented bugs + $100K/year in faster onboarding = $450K annual return on $50K investment. Timeline: improvements visible in 30 days (automation), fully realized in 90 days (process changes). Dashboard: CEO-level metrics — cycle time trend, defect rate trend, developer satisfaction trend, features delivered per quarter"
+    weight: 0.30
+    description: "CEO recommendation"

package/courses/code-review-feedback-writing/scenarios/level-5/scaling-reviews-100-plus.yaml

@@ -0,0 +1,45 @@
+meta:
+  id: scaling-reviews-100-plus
+  level: 5
+  course: code-review-feedback-writing
+  type: output
+  description: "Scale reviews to 100+ engineers — design review processes that maintain quality and culture at large scale across multiple teams, timezones, and experience levels"
+  tags: [code-review, scaling, large-team, process-design, multi-timezone, master]
+
+state: {}
+
+trigger: |
+  Your company is growing from 50 to 200 engineers over 18 months.
+  The current review process works well at 50 but won't scale:
+
+  - Manual reviewer assignment (team lead picks reviewers)
+  - One review channel in Slack (50 engineers, manageable noise)
+  - Informal mentoring through review (seniors know all juniors)
+  - Single coding standard (everyone agreed in one meeting)
+  - Everyone knows everyone (trust is personal, not institutional)
+
+  At 200 engineers across 4 timezones:
+  - Team lead can't know everyone's expertise
+  - Slack channel becomes unusable noise
+  - Seniors can't personally mentor 150 juniors
+  - Standards need to be written (can't be tribal knowledge)
+  - Trust must be institutional (process-based, not personal)
+
+  Task: Design the review process for 200 engineers. Include:
+  automated assignment, tiered review requirements, timezone-aware
+  scheduling, knowledge preservation systems, and how to maintain
+  the collaborative culture that worked at 50 people.
+
+assertions:
+  - type: llm_judge
+    criteria: "Automated systems replace manual coordination — assignment: CODEOWNERS + automated round-robin weighted by: expertise (code area familiarity), load (current open reviews), timezone (prefer same or adjacent timezone for sync discussions), cross-pollination (10% of assignments go to engineers outside the team for knowledge sharing). Tiered requirements: Tier 1 (low risk: docs, config, style) — 1 approval, any engineer. Tier 2 (standard: features, refactors) — 1 approval, team member. Tier 3 (high risk: security, data, infrastructure) — 2 approvals, at least 1 senior. Tier auto-detected: CI analyzes changed files against CODEOWNERS patterns. Slack: replace single channel with per-team channels + cross-team review request bot. Dashboard: real-time review queue visibility per team"
+    weight: 0.35
+    description: "Automated systems"
+  - type: llm_judge
+    criteria: "Timezone awareness prevents review latency — async-first design: reviews should be completable without real-time discussion (high-quality PR descriptions, thorough first review pass). Timezone routing: assign reviewers in same or +/- 4 hour timezone when possible. Follow-the-sun for urgent reviews: if no reviewer available in requester's timezone, auto-escalate to next timezone's pool. SLA adjustment by timezone overlap: same timezone = 8 hours, adjacent = 16 hours, opposite = 24 hours. Review handoff: if review discussion is complex, write summary for the next timezone reviewer rather than waiting for sync. Critical path: reviews blocking production deploys get priority routing regardless of timezone. Meeting-light: replace synchronous design reviews with async RFC documents + async review comments"
+    weight: 0.35
+    description: "Timezone design"
+  - type: llm_judge
+    criteria: "Culture preservation strategy is explicit — what to preserve from 50-person culture: (1) constructive tone — encode in written guidelines with examples, enforce via manager review. (2) Mentoring — replace personal mentoring with structured program: each junior paired with a mentor-reviewer for 6 months. (3) Trust — shift from personal trust ('I know Alex does good work') to process trust ('this PR passed our quality gates'). (4) Shared ownership — cross-team review rotation prevents silos. What to let go: (1) everyone knowing everyone (impossible at 200), (2) single review channel (too noisy), (3) ad-hoc standards (must be documented). New at scale: (1) written review culture document (onboarding reading), (2) review quality calibration (quarterly, team-level), (3) review recognition program (celebrate excellent reviews monthly), (4) review retrospectives (what's working, what's not, quarterly). Success metric: 'Would a new hire who joined 3 months ago describe our review culture the same way a 3-year veteran would?'"
+    weight: 0.30
+    description: "Culture preservation"

package/courses/code-review-feedback-writing/scenarios/level-5/toxic-culture-transformation.yaml

@@ -0,0 +1,46 @@
+meta:
+  id: toxic-culture-transformation
+  level: 5
+  course: code-review-feedback-writing
+  type: output
+  description: "Transform toxic review culture — diagnose and systematically fix an adversarial code review environment, rebuilding trust and psychological safety"
+  tags: [code-review, culture-transformation, psychological-safety, trust, toxic, master]
+
+state: {}
+
+trigger: |
+  You're brought in as CTO of a 150-person engineering org where
+  code review culture is actively harmful:
+
+  - Exit interviews: "code reviews felt like personal attacks"
+  - Two teams refuse to request review from each other (feud)
+  - A "hall of shame" Slack channel where bad code from reviews is mocked
+  - Senior engineers use reviews to demonstrate superiority
+  - Junior developers submit PRs with apologies: "I know this isn't
+    great, please don't be too harsh"
+  - Code quality is actually declining — harsh reviews make developers
+    hide code rather than seeking feedback
+  - 25% attrition rate among engineers under 2 years tenure
+
+  The technical bar IS high and needs to stay high. The challenge:
+  maintain quality standards while completely transforming the culture.
+
+  Task: Present the culture transformation plan. Include: diagnosis
+  of how the culture became toxic, immediate interventions (first 2
+  weeks), 90-day transformation program, how to handle the specific
+  bad actors, metrics for measuring cultural change, and how to
+  maintain high quality standards in a psychologically safe environment.
+
+assertions:
+  - type: llm_judge
+    criteria: "Diagnosis explains how the culture became toxic — root causes: (1) review quality was never defined — 'rigorous' was conflated with 'harsh.' (2) Senior engineers were rewarded for catching bugs, not for mentoring. (3) Management tolerated hostile behavior because the engineers were 'high performers.' (4) No consequences for abusive comments — normalized over time. (5) 'Hall of shame' channel started as humor, became bullying. (6) Junior developers internalized that asking for help = weakness. Systemic pattern: the culture rewards proving you're smart over helping others get smarter. This creates competition, not collaboration. Quality actually suffers: developers hide problems, avoid asking questions, submit smaller PRs to minimize exposure — all of which reduce code quality and knowledge sharing"
+    weight: 0.35
+    description: "Diagnosis"
+  - type: llm_judge
+    criteria: "Immediate interventions stop the bleeding — week 1: (1) shut down the 'hall of shame' channel immediately — public announcement: 'Mocking colleagues' code is incompatible with our values.' (2) 1:1 meetings with the worst offenders — clear expectations and consequences. (3) All-hands meeting: 'Code review is being reformed. High quality standards remain. Hostile behavior stops today.' (4) Anonymous feedback channel for reporting review abuse. Week 2: (1) interim review guidelines published (tone requirements, comment labels), (2) review moderation — manager spot-checks reviews for the next 30 days, (3) skip-level 1:1s with junior developers to hear their experience, (4) inter-team feud: facilitated meeting with both team leads, mediated by engineering manager. Handling bad actors: progressive — warning, coaching, performance plan, termination. 'We can teach kind feedback; we can't teach willingness to be kind.'"
+    weight: 0.35
+    description: "Immediate interventions"
+  - type: llm_judge
+    criteria: "90-day program rebuilds trust with measurable outcomes — month 1 (safety): training on constructive feedback (mandatory, all engineers), reviewer code of conduct, celebrate examples of excellent review comments. Month 2 (skill): pair reviewing program (senior + junior), review quality as performance criteria, cross-team review exchanges to break feuds. Month 3 (sustainability): metrics dashboard (review tone, turnaround, satisfaction), recognition program for mentoring through review, quarterly culture survey. Metrics: (1) survey: 'I feel safe submitting PRs for review' — target 80% agree (from estimated 30%), (2) attrition rate for < 2yr tenure — target 15% (from 25%), (3) review comment sentiment analysis — track positive/negative ratio, (4) PR submission frequency — should increase as safety increases. Quality maintenance: defect escape rate and rollback rate should NOT increase — if they do, adjust. The thesis: psychological safety IMPROVES quality because people seek feedback instead of hiding mistakes"
+    weight: 0.30
+    description: "Transformation program"

package/courses/technical-rfc-writing/course.yaml

@@ -0,0 +1,11 @@
+id: technical-rfc-writing
+name: "Technical RFC Writing"
+description: >
+  Master technical RFC writing from basic problem statements and
+  solution proposals to enterprise technology governance through
+  structured decision-making documents. Progress through RFC structure,
+  trade-off analysis, cross-team coordination, organizational RFC
+  programs, and strategic technology decision frameworks.
+levels: 5
+scenarios_per_level: 10
+tags: [writing, RFC, design-docs, technical-decisions, architecture, proposals]

package/courses/technical-rfc-writing/scenarios/level-1/first-rfc-shift.yaml

@@ -0,0 +1,45 @@
+meta:
+  id: first-rfc-shift
+  level: 1
+  course: technical-rfc-writing
+  type: output
+  description: "First RFC shift simulation — write a complete RFC from scratch combining all fundamentals: problem statement, solution, alternatives, risks, implementation plan, and success metrics"
+  tags: [RFC, shift-simulation, complete-rfc, synthesis, beginner]
+
+state: {}
+
+trigger: |
+  You've been asked to write your first complete RFC. The situation:
+
+  Your team's deployment process is painful:
+  - Deployments happen manually via SSH by a single senior engineer
+  - Only 2 people know the deployment process (bus factor = 2)
+  - Deployments take 45 minutes and require a "deployment window"
+  - Last month, 3 out of 8 deployments caused incidents requiring rollback
+  - Rollbacks are also manual and take 30 minutes
+  - The team deploys only twice a week because deployments are risky
+  - Feature work is piling up — there's a 3-week backlog of merged PRs
+    waiting to be deployed
+
+  You want to propose implementing a CI/CD pipeline with automated
+  testing, staged rollouts, and automated rollback.
+
+  Task: Write a complete RFC including all standard sections: summary,
+  problem statement (with data), proposed solution, alternatives
+  considered, risks and mitigations, implementation plan (phased),
+  success metrics, and open questions. This is your synthesis exercise
+  — demonstrate everything you've learned about RFC writing.
+
+assertions:
+  - type: llm_judge
+    criteria: "RFC has all standard sections with appropriate depth — Summary: 2-3 sentences capturing the proposal, impact, and timeline. Problem Statement: data-driven (45-min deploys, 37.5% failure rate, 2-person bus factor, 3-week backlog), business impact (delayed features, incident costs, engineer frustration), urgency (getting worse as team grows). Proposed Solution: CI/CD pipeline with specific choices (e.g., GitHub Actions, staged rollouts via feature flags or canary), enough detail to evaluate but not an implementation guide. Alternatives Considered: at least 2 alternatives fairly presented (e.g., documented manual process with checklist, partial automation with deploy scripts), each with honest pros/cons and specific reasons for rejection. Risks: specific risks with mitigations (pipeline reliability, learning curve, migration period where both systems exist). Implementation Plan: phased (automated tests first, then CI builds, then CD to staging, then CD to production), with milestones and timeline. Success Metrics: deployment frequency, failure rate, rollback time, time-to-production. Open Questions: 2-3 genuine unresolved decisions with context and preliminary thinking"
+    weight: 0.35
+    description: "Complete RFC structure"
+  - type: llm_judge
+    criteria: "RFC sections are internally consistent and well-connected — the problem statement's data (37.5% failure rate, 45-minute deploys) is directly referenced in the success metrics ('reduce deployment failure rate to under 5%, reduce deployment time to under 10 minutes'). The proposed solution addresses every problem mentioned (manual process → automated, bus factor → documented pipeline, slow rollbacks → automated rollback). The risks section acknowledges realistic challenges with the proposed solution, not just risks of doing nothing. The implementation plan phases align with the solution description. The alternatives section explains why they don't solve the problems as well. Open questions are genuinely unresolved (not things already decided in the solution section). The reader should feel this is one coherent document, not disconnected sections written independently"
+    weight: 0.35
+    description: "Internal consistency"
+  - type: llm_judge
+    criteria: "RFC demonstrates good writing practices throughout — executive-friendly summary that a VP could read and understand the proposal. Problem statement leads with impact, not technical details. Solution section explains WHY this approach, not just WHAT it is. Alternatives are steel-manned (presented fairly, not as straw men). Risks are honest (doesn't hide difficulties to make the proposal look better). Implementation plan is realistic (includes buffer time, go/no-go criteria between phases). Success metrics have baselines and targets. Open questions show intellectual humility (acknowledges what the author doesn't know). Tone throughout is confident but not arrogant — 'we recommend' not 'we must', acknowledges trade-offs rather than presenting the solution as perfect. The RFC should serve all audiences: an engineer should find enough detail to evaluate feasibility, a manager should find timeline and resources, a VP should find business justification"
+    weight: 0.30
+    description: "Writing quality"

package/courses/technical-rfc-writing/scenarios/level-1/implementation-planning.yaml

@@ -0,0 +1,47 @@
+meta:
+  id: implementation-planning
+  level: 1
+  course: technical-rfc-writing
+  type: output
+  description: "Write an implementation plan — break a proposed solution into phases with milestones, dependencies, and a realistic timeline"
+  tags: [RFC, implementation, planning, phasing, milestones, beginner]
+
+state: {}
+
+trigger: |
+  You're writing the implementation plan section of an RFC. The proposal:
+  migrate your monolithic Node.js application to a containerized
+  deployment using Docker and Kubernetes.
+
+  Current state:
+  - Single Node.js app running on 3 EC2 instances behind a load balancer
+  - Deployments via SSH + PM2 (manual, error-prone)
+  - No health checks beyond basic ping
+  - Environment config stored in .env files on each server
+
+  Target state:
+  - Dockerized application with CI/CD pipeline
+  - Kubernetes cluster with auto-scaling
+  - Health checks and readiness probes
+  - Config managed via Kubernetes secrets/configmaps
+
+  Your first draft says: "Phase 1: Set up Kubernetes. Phase 2: Migrate.
+  Phase 3: Done." This doesn't help anyone plan their work.
+
+  Task: Write a detailed implementation plan that breaks this migration
+  into realistic phases with clear milestones, dependencies, and a
+  timeline. Then write a guide on how to plan implementations in RFCs.
+
+assertions:
+  - type: llm_judge
+    criteria: "Implementation is broken into clear, sequenced phases — Phase 1 (Weeks 1-2): Containerization — Dockerize the application, create Dockerfile and docker-compose for local development, set up container registry, validate that containerized app passes all existing tests. Milestone: app runs identically in Docker as on bare metal. No infrastructure changes yet. Phase 2 (Weeks 3-4): CI/CD Pipeline — set up automated builds on push, container image scanning, automated testing in containers, deployment to staging Kubernetes cluster. Milestone: every merge to main produces a tested, deployable container image. Phase 3 (Weeks 5-6): Kubernetes Setup — provision production cluster, configure networking and ingress, set up secrets management, implement health checks and readiness probes. Milestone: staging environment runs reliably on Kubernetes for 1 week. Phase 4 (Weeks 7-8): Production Migration — gradual traffic shift (10% → 50% → 100%), monitoring and rollback readiness, decommission old EC2 instances after 2 weeks of stable operation. Milestone: 100% traffic on Kubernetes with no degradation. Each phase is independently valuable and shippable"
+    weight: 0.35
+    description: "Phased implementation"
+  - type: llm_judge
+    criteria: "Dependencies and risks per phase are identified — dependencies between phases are explicit: 'Phase 2 depends on Phase 1 (need Docker images before CI/CD can build them). Phase 4 depends on Phase 3 (need cluster before migration).' External dependencies: 'Kubernetes cluster provisioning requires infrastructure team approval (1 week lead time — start in Phase 1).' Team allocation: 'Phases 1-2 require 2 backend engineers. Phase 3 requires 1 infrastructure engineer + 1 backend engineer. Phase 4 is all-hands for monitoring.' Go/no-go criteria between phases: 'Do not start Phase 4 until Phase 3 staging environment has run without incidents for 5 business days.' Rollback plan per phase: 'At any point before Phase 4 reaches 100%, we can route all traffic back to EC2 instances within 5 minutes.' Parallel work identified: 'CI/CD setup (Phase 2) and Kubernetes provisioning (Phase 3) can overlap in weeks 3-4'"
+    weight: 0.35
+    description: "Dependencies and sequencing"
+  - type: llm_judge
+    criteria: "Planning guide provides reusable principles — principles: (1) Work backwards from the goal: what's the last thing that needs to happen? What must be true before that? Keep going until you reach today. (2) Each phase should be independently valuable: if the project is cancelled after Phase 2, you should still have gained something (containerized app with CI/CD is valuable even without Kubernetes). (3) Front-load risk reduction: tackle the hardest, most uncertain work first — if it fails, you've wasted less time. (4) Include buffer time: estimate honestly then add 20-30% for unknowns. A plan that requires everything to go perfectly is not a plan. (5) Define milestones as verifiable states, not activities: 'app passes load test at 2x current traffic' not 'finish load testing.' (6) Identify the critical path: which tasks, if delayed, delay the entire project? These get the most attention and resources. Anti-patterns: phases that are just calendar months with no milestones, plans with no rollback strategy, big-bang migrations with no gradual rollout, and plans that assume zero dependencies on other teams"
+    weight: 0.30
+    description: "Planning guide"

package/courses/technical-rfc-writing/scenarios/level-1/open-questions.yaml

@@ -0,0 +1,46 @@
+meta:
+  id: open-questions
+  level: 1
+  course: technical-rfc-writing
+  type: output
+  description: "Write open questions — identify unresolved decisions in an RFC and frame them to get useful input from reviewers"
+  tags: [RFC, open-questions, decisions, feedback, collaboration, beginner]
+
+state: {}
+
+trigger: |
+  You're writing the open questions section of an RFC proposing to
+  introduce a message queue (like RabbitMQ, Kafka, or SQS) for
+  asynchronous processing. Currently, your application processes
+  everything synchronously, causing timeouts on heavy operations
+  like report generation, email sending, and image processing.
+
+  You have several unresolved questions:
+  - Which message queue technology to use
+  - Whether to start with one queue or separate queues per task type
+  - How to handle failed messages (retry? dead letter queue?)
+  - Whether to build a custom worker or use an existing framework
+  - What the message format should be (JSON? Protobuf? Avro?)
+  - Who owns the queue infrastructure (your team or platform team?)
+
+  Your first draft just lists these as bullet points. Reviewers
+  respond with "I don't know, what do you think?" because the
+  questions aren't framed to help people give useful answers.
+
+  Task: Write an open questions section that frames each question
+  with context, constraints, options, and your preliminary thinking.
+  Then write a guide on how to use open questions effectively in RFCs.
+
+assertions:
+  - type: llm_judge
+    criteria: "Open questions are well-framed with context and options — each question provides: (1) Why it matters: 'Message queue technology selection affects operational complexity, cost, and future scalability.' (2) Constraints: 'We need at-least-once delivery, message persistence, and support for delayed messages. Budget constraint: under $500/month for expected volume.' (3) Options considered: 'RabbitMQ (familiar to team, good for task queues, self-hosted), SQS (managed, lowest ops burden, AWS-native), Kafka (highest throughput, but overkill for our volume of ~1000 messages/hour).' (4) Preliminary recommendation: 'Leaning toward SQS because managed service reduces operational burden and our volume doesn't justify Kafka's complexity. However, if we anticipate event streaming needs in 6 months, Kafka may be worth the upfront investment.' The reviewer now has enough context to give an informed opinion rather than starting from scratch"
+    weight: 0.35
+    description: "Well-framed questions"
+  - type: llm_judge
+    criteria: "Questions are prioritized and categorized — blocking questions (must resolve before implementation): queue technology choice (affects all other decisions), failure handling strategy (affects message format and retry logic). Non-blocking questions (can decide during implementation): single vs multiple queues (can start with one and split later), message format (can evolve with versioning). Ownership questions (need organizational input): infrastructure ownership (requires manager/platform team input, not a technical decision). For each question: deadline for decision ('queue technology must be decided before Phase 1 starts — targeting end of review period'), who should weigh in ('platform team for infrastructure ownership, backend engineers for technology choice'), and what happens if not decided ('if no consensus on queue tech, we default to SQS as the lowest-risk managed option'). Default decisions prevent open questions from blocking progress indefinitely"
+    weight: 0.35
+    description: "Prioritized questions"
+  - type: llm_judge
+    criteria: "Guide explains how to use open questions effectively — principles: (1) Open questions should be genuine unknowns, not things you're too lazy to decide. If you have enough information to make a decision, make it and state your reasoning — don't punt to reviewers. (2) Frame questions to reduce cognitive load: don't ask 'what should we use?' — ask 'should we use A or B, given these trade-offs?' (3) Include your preliminary thinking: reviewers can critique a proposal faster than generate one from scratch. 'I'm leaning toward X because Y' invites 'have you considered Z?' which is more useful than starting from blank. (4) Set decision deadlines: open questions without timelines stay open forever. 'If no input by Friday, we'll proceed with SQS.' (5) Limit to 3-5 questions: if you have 15 open questions, your RFC isn't ready for review — you need more research. (6) Track resolution: update the RFC as questions are answered. Mark resolved questions so future readers don't re-debate settled decisions. Anti-patterns: rhetorical questions (you already know the answer), questions that should be separate RFCs, questions designed to shift responsibility, and questions so vague that any answer works"
+    weight: 0.30
+    description: "Open questions guide"

package/courses/technical-rfc-writing/scenarios/level-1/problem-statement.yaml

@@ -0,0 +1,41 @@
+meta:
+  id: problem-statement
+  level: 1
+  course: technical-rfc-writing
+  type: output
+  description: "Write a clear problem statement — articulate the problem an RFC addresses with context, impact, and urgency that motivates the reader to care"
+  tags: [RFC, problem-statement, context, impact, motivation, beginner]
+
+state: {}
+
+trigger: |
+  You need to write the problem statement section of an RFC. The
+  technical problem: your API response times have degraded from
+  100ms to 800ms over the past 6 months as the database grew from
+  1M to 10M rows. Several key customers have complained. The team
+  has discussed solutions informally but nothing is documented.
+
+  Bad problem statements you've seen:
+  - "The API is slow" (too vague)
+  - "We need to add caching" (jumps to solution)
+  - A 3-page history of the entire system (too much context)
+  - "P99 latency is 800ms" (data without context or impact)
+
+  Task: Write a problem statement that clearly articulates: what the
+  problem is (with data), who is affected, what the impact is (business
+  and technical), how urgent it is, and what happens if we don't act.
+  Then write a guide on what makes a good problem statement.
+
+assertions:
+  - type: llm_judge
+    criteria: "Problem statement includes data, context, and impact — data: 'API response times increased from 100ms (p50) to 800ms (p99) over 6 months as our users table grew from 1M to 10M rows.' Context: 'This degradation corresponds with organic user growth. Query execution plans show full table scans on unindexed columns.' Impact: business ('3 enterprise customers escalated to their account managers, 2 are evaluating competitors'), technical ('downstream services timeout, causing cascading failures during peak hours'). Urgency: 'At current growth rate, we'll reach 20M rows in 4 months. Without intervention, p99 latency will exceed 2 seconds, breaching our SLA commitments.' The statement makes the reader understand WHY this RFC exists and WHY it matters NOW"
+    weight: 0.35
+    description: "Data and impact"
+  - type: llm_judge
+    criteria: "Problem statement avoids common pitfalls — doesn't jump to solutions (no mention of caching, indexing, or any specific fix in the problem section). Doesn't include unnecessary history (only relevant context, not the entire system's evolution). Isn't too vague ('API is slow') or too narrow ('index needed on users.created_at'). Separates symptoms (slow API) from root cause (query patterns on growing tables). Quantifies scope: which endpoints are affected, what percentage of requests, which customers. Distinguishes between the problem (slow queries) and the constraint (can't just throw hardware at it because costs). States success criteria: 'We need to return to sub-200ms p99 latency while supporting 50M+ rows'"
+    weight: 0.35
+    description: "Avoids pitfalls"
+  - type: llm_judge
+    criteria: "Guide explains what makes problem statements effective — principles: (1) Start with impact, not technical details — the reader should care before they understand. (2) Include data — 'slow' is subjective, '800ms p99' is measurable. (3) Show the trend — not just current state but trajectory ('getting worse at X rate'). (4) Separate problem from solution — the problem section should be agreeable regardless of which solution is chosen. (5) Define success — what does 'solved' look like? (measurable criteria). (6) State urgency — what happens if we wait? (timeline and consequences). Anti-patterns: solution-oriented problem statements ('we need caching'), blame-oriented ('the previous developer didn't add indexes'), scope-creep ('while we're at it, let's also...'). The problem statement is the foundation — if reviewers disagree on the problem, the solution discussion is pointless"
+    weight: 0.30
+    description: "Problem statement guide"

package/courses/technical-rfc-writing/scenarios/level-1/proposing-solutions.yaml

@@ -0,0 +1,49 @@
+meta:
+  id: proposing-solutions
+  level: 1
+  course: technical-rfc-writing
+  type: output
+  description: "Propose solutions with alternatives — present a recommended approach alongside alternatives considered, with clear reasoning for the recommendation"
+  tags: [RFC, solutions, alternatives, recommendation, reasoning, beginner]
+
+state: {}
+
+trigger: |
+  You're writing the solution section of an RFC. The problem: your
+  application needs real-time notifications. You've researched three
+  approaches:
+
+  1. Polling: clients poll API every 5 seconds
+     - Pros: simple, works everywhere, no infrastructure changes
+     - Cons: high server load, 5-second delay, wastes bandwidth
+
+  2. WebSocket: persistent connection for real-time push
+     - Pros: instant delivery, low latency, bidirectional
+     - Cons: connection management complexity, load balancer config,
+       harder to scale horizontally
+
+  3. Server-Sent Events (SSE): server pushes over HTTP
+     - Pros: simpler than WebSocket, automatic reconnection, works
+       through most proxies
+     - Cons: unidirectional only, limited browser connection pool
+
+  You recommend SSE.
+
+  Task: Write the "Proposed Solution" and "Alternatives Considered"
+  sections. Show how to present your recommendation with reasoning
+  while fairly representing the alternatives. The reader should
+  understand WHY SSE was chosen, not just THAT it was chosen.
+
+assertions:
+  - type: llm_judge
+    criteria: "Recommendation is clearly stated with reasoning — the proposed solution section leads with the recommendation: 'We recommend Server-Sent Events (SSE) for real-time notifications.' Then explains WHY: (1) Our use case is unidirectional (server → client), so WebSocket's bidirectional capability is unnecessary complexity. (2) SSE's automatic reconnection handles network instability (common on mobile) without custom code. (3) SSE works through existing load balancers and proxies without configuration changes. (4) Simpler to implement than WebSocket while meeting all requirements. Decision criteria explicitly stated: we optimized for simplicity and reliability over maximum capability. The reasoning should be convincing — a reader should agree with the choice after reading the justification"
+    weight: 0.35
+    description: "Clear recommendation"
+  - type: llm_judge
+    criteria: "Alternatives are fairly represented — each alternative: (1) described accurately (not straw-manned to make the recommendation look better), (2) pros acknowledged (polling IS simpler, WebSocket IS more capable), (3) specific reasons for rejection tied to THIS project's needs. Polling rejected: 'Polling at 5-second intervals for 10,000 concurrent users = 2,000 requests/second. This triples our API load and still has unacceptable latency for time-sensitive notifications (payment confirmations).' WebSocket rejected: 'WebSocket requires significant infrastructure changes (sticky sessions, WebSocket-aware load balancer) and custom reconnection logic. The capability gain (bidirectional) doesn't justify the complexity for our unidirectional notification use case.' A reader favoring an alternative should feel their option was genuinely considered, not dismissed"
+    weight: 0.35
+    description: "Fair alternatives"
+  - type: llm_judge
+    criteria: "Decision matrix or comparison is provided — structured comparison: table with criteria (latency, complexity, scalability, infrastructure changes, browser support) × options. Each cell has a specific value, not just 'good/bad.' Under what conditions the recommendation changes: 'If we later need bidirectional communication (e.g., real-time collaboration features), we should revisit WebSocket.' 'If we need to support very old browsers, polling becomes the fallback.' This shows the recommendation isn't dogmatic — it's the best choice for current requirements. Reversibility: 'SSE and WebSocket have similar client-side interfaces — migrating from SSE to WebSocket later is straightforward (estimated 2 weeks). This makes SSE a low-risk starting point.'"
+    weight: 0.30
+    description: "Comparison structure"

package/courses/technical-rfc-writing/scenarios/level-1/rfc-structure.yaml

@@ -0,0 +1,41 @@
+meta:
+  id: rfc-structure
+  level: 1
+  course: technical-rfc-writing
+  type: output
+  description: "Learn RFC structure — understand the standard sections of a technical RFC and what each section should contain"
+  tags: [RFC, structure, sections, template, format, beginner]
+
+state: {}
+
+trigger: |
+  Your team wants to start writing RFCs for technical decisions but
+  no one has written one before. You need to explain the standard
+  RFC structure and create a template the team can use.
+
+  The team has questions:
+  - "How long should an RFC be?"
+  - "What sections are required vs optional?"
+  - "Who is the audience for each section?"
+  - "How detailed should the technical design be?"
+  - "What's the difference between an RFC and a design doc?"
+
+  Task: Write a comprehensive guide to RFC structure. Include: each
+  standard section with its purpose and audience, guidelines for
+  length and detail, a reusable template with prompts for each
+  section, and an explanation of when an RFC is appropriate vs
+  other document types.
+
+assertions:
+  - type: llm_judge
+    criteria: "Standard sections are defined with clear purposes — sections: (1) Title and metadata (author, date, status, reviewers). (2) Summary/TL;DR (1-2 paragraphs for executives and time-pressed readers). (3) Problem Statement (what problem, who's affected, why now). (4) Proposed Solution (the recommended approach, enough detail to evaluate). (5) Alternatives Considered (other approaches and why they were rejected). (6) Technical Design (architecture, data model, API changes, sequence diagrams). (7) Risks and Mitigations (what could go wrong, how to handle it). (8) Implementation Plan (phases, timeline, milestones). (9) Success Metrics (how to measure if the solution works). (10) Open Questions (unresolved decisions needing input). Each section: who reads it (manager reads summary, engineers read design), and what it should NOT include"
+    weight: 0.35
+    description: "Section definitions"
+  - type: llm_judge
+    criteria: "Length and detail guidelines are practical — total length: 2-6 pages for most RFCs (not counting appendices). If longer, the scope is probably too broad — split into multiple RFCs. Summary: 2-3 sentences (the 'elevator pitch'). Problem statement: half a page (focused, data-driven). Solution: 1-2 pages (enough detail to evaluate, not enough to implement — that's the code). Alternatives: half page per alternative (brief, focus on why rejected). Design: as detailed as needed (diagrams encouraged, pseudocode over real code). Risks: bullet points, not paragraphs. Implementation: phased, with milestones. Rule of thumb: if you can't explain the proposal in 5 pages, you need to simplify or split. Appendices for supplementary data (benchmark results, detailed schemas)"
+    weight: 0.35
+    description: "Length guidelines"
+  - type: llm_judge
+    criteria: "RFC vs other document types is clearly explained — RFC: proposes a significant technical decision that needs team/org input. Use when: change affects multiple teams, multiple valid approaches exist, decision is hard to reverse. Design doc: detailed implementation plan for an already-decided approach. ADR (Architecture Decision Record): lightweight record of a decision already made (retrospective). Tech spec: detailed specification for implementers (API contracts, data schemas). One-pager: brief proposal for smaller decisions. When NOT to write an RFC: trivial decisions, already-decided approaches that just need implementation, urgent fixes (fix first, document later). Hierarchy: RFC (proposal, needs consensus) → ADR (decision recorded) → Design doc (implementation plan) → Tech spec (implementation details)"
+    weight: 0.30
+    description: "RFC vs other docs"

package/courses/technical-rfc-writing/scenarios/level-1/risks-and-mitigations.yaml

@@ -0,0 +1,43 @@
+meta:
+  id: risks-and-mitigations
+  level: 1
+  course: technical-rfc-writing
+  type: output
+  description: "Write risks and mitigations — identify what could go wrong with a proposed solution and present concrete mitigation strategies"
+  tags: [RFC, risks, mitigations, planning, failure-modes, beginner]
+
+state: {}
+
+trigger: |
+  You're writing the risks section of an RFC proposing to migrate your
+  application from a self-hosted PostgreSQL database to a managed cloud
+  database service (like AWS RDS or Google Cloud SQL).
+
+  The migration involves:
+  - Moving 500GB of production data
+  - Changing connection strings across 12 microservices
+  - Switching from self-managed backups to provider-managed backups
+  - New network topology (VPC peering instead of local connections)
+
+  Your first draft just lists: "Risk: data loss. Risk: downtime."
+  This isn't helpful — it doesn't tell reviewers HOW LIKELY risks are,
+  HOW SEVERE they'd be, or WHAT YOU'LL DO about them.
+
+  Task: Write a comprehensive risks and mitigations section for this
+  RFC. For each risk, include likelihood, severity, impact, and a
+  concrete mitigation plan. Then write a guide on how to think about
+  risks in technical proposals.
+
+assertions:
+  - type: llm_judge
+    criteria: "Risks are specific with likelihood and severity — not generic 'data loss' but specific: (1) 'Data corruption during migration: rows with special characters or encoding issues may fail transfer. Likelihood: Medium. Severity: High. Mitigation: run migration on a staging copy first, validate row counts and checksums per table, keep source database read-only during final sync.' (2) 'Extended downtime beyond maintenance window: migration of 500GB may exceed the 4-hour window if network throughput is lower than expected. Likelihood: Low. Severity: High. Mitigation: perform dry runs to measure actual transfer rates, have a go/no-go checkpoint at 2 hours, pre-stage data with continuous replication before cutover.' (3) 'Connection string misconfiguration: 12 services need updated connection strings — missing one causes partial outage. Likelihood: Medium. Severity: Medium. Mitigation: use environment variables managed by config service, deploy connection changes before migration, test each service against new endpoint in staging.' (4) 'Increased latency from network topology change: VPC peering adds ~1-2ms per query vs local connections. Likelihood: High. Severity: Low. Mitigation: benchmark critical query paths, implement connection pooling, consider read replicas for latency-sensitive services.' Each risk should feel researched, not speculative"
+    weight: 0.35
+    description: "Specific risks"
+  - type: llm_judge
+    criteria: "Mitigations are actionable, not hand-wavy — each mitigation answers: what specifically will be done, who is responsible, when it happens (before/during/after migration), and what the fallback is if mitigation fails. Includes a rollback plan: 'If critical issues are discovered within 48 hours of migration, we can fail back to the original database. Continuous replication from new to old database will be maintained during the validation period.' Risk acceptance: explicitly acknowledges which risks are accepted ('We accept 1-2ms latency increase as an acceptable trade-off for managed backups and reduced operational burden'). Residual risks: 'Even with mitigations, there is a non-zero chance of brief inconsistency during cutover. This is bounded to a 30-second window and affects only write operations.' No mitigation should be 'we'll be careful' — every mitigation is a concrete action"
+    weight: 0.35
+    description: "Actionable mitigations"
+  - type: llm_judge
+    criteria: "Risk guide provides a framework for thinking about risks — principles: (1) Categorize risks: technical (will it work?), operational (can we run it?), timeline (will it be late?), organizational (do we have the skills?). (2) Use likelihood × severity to prioritize — high likelihood + high severity = must mitigate, low likelihood + low severity = accept and monitor. (3) Every risk needs an owner — 'the team will handle it' means nobody handles it. (4) Distinguish between risks you can prevent and risks you can only detect and respond to. (5) Include rollback criteria — under what conditions do you abort? Make these specific and pre-agreed. (6) Time-bound your risk window — 'risk of data loss exists only during the 4-hour migration window, not before or after.' Anti-patterns: ignoring risks to make the RFC look better, listing risks without mitigations (anxiety without action), mitigating everything (some risks should be accepted), and confusing risks with issues (a risk MIGHT happen, an issue already exists)"
+    weight: 0.30
+    description: "Risk framework guide"

package/courses/technical-rfc-writing/scenarios/level-1/scoping-an-rfc.yaml

@@ -0,0 +1,49 @@
+meta:
+  id: scoping-an-rfc
+  level: 1
+  course: technical-rfc-writing
+  type: output
+  description: "Scope an RFC appropriately — determine what should be in scope, out of scope, and how to handle scope creep in technical proposals"
+  tags: [RFC, scoping, boundaries, focus, scope-creep, beginner]
+
+state: {}
+
+trigger: |
+  You're writing an RFC to add search functionality to your e-commerce
+  platform. As you write, the scope keeps growing:
+
+  Started as: "Add product search with text matching"
+
+  Expanded to include:
+  - Full-text search with relevance ranking
+  - Autocomplete suggestions
+  - Search analytics (what users search for)
+  - Faceted filtering (by category, price, brand)
+  - Personalized search results (based on user history)
+  - Multi-language search support
+  - Image-based search ("search by photo")
+  - Voice search integration
+  - Search result caching strategy
+  - A/B testing framework for search ranking
+
+  Each addition is genuinely useful, but the RFC is now a 6-month
+  project that no one will approve.
+
+  Task: Write the scoping section for this RFC. Decide what's in
+  scope (phase 1), what's explicitly out of scope (with reasoning),
+  and what's future work (acknowledged but deferred). Then write a
+  guide on how to scope technical proposals effectively.
+
+assertions:
+  - type: llm_judge
+    criteria: "Phase 1 scope is focused and deliverable — in scope: full-text search with relevance ranking (core feature), faceted filtering by category and price (expected UX), search result caching (performance requirement). These form a coherent, shippable feature. Timeline: 4-6 weeks. Explicitly out of scope: autocomplete (separate RFC — different backend architecture), personalized search (requires ML infrastructure not yet built), image search (R&D project, not engineering), voice search (depends on voice input infrastructure), A/B testing framework (separate cross-cutting concern). Future work (acknowledged): search analytics (phase 2, enables data-driven improvements), multi-language support (phase 2, when internationalization begins). Each out-of-scope item has a brief reason WHY it's deferred"
+    weight: 0.35
+    description: "Focused scope"
+  - type: llm_judge
+    criteria: "Out-of-scope decisions are justified, not arbitrary — each deferral: reason tied to constraints or dependencies. Autocomplete: 'Requires a dedicated suggestion index and real-time query infrastructure that's a separate architectural decision.' Personalization: 'Depends on user behavior tracking and ML pipeline that don't exist yet. Building search infrastructure first provides the data foundation for personalization later.' Image search: 'Requires computer vision capabilities we haven't evaluated. This is a research question, not an engineering decision.' Each deferred item includes: when it could be addressed ('after phase 1 data validates the search approach') and what would trigger revisiting ('if user research shows autocomplete is critical for conversion'). The reader should feel that scope was carefully considered, not randomly cut"
+    weight: 0.35
+    description: "Justified boundaries"
+  - type: llm_judge
+    criteria: "Scoping guide provides reusable principles — principles: (1) The MVP test: what's the smallest scope that solves the core problem? Start there. (2) Dependency check: does this feature require infrastructure that doesn't exist? If yes, scope it out. (3) Two-week rule: if a single scope item takes more than 2 weeks, it might be its own RFC. (4) Reversibility: prefer scope that's easy to extend later over scope that's hard to change (build basic search, then add personalization — not the reverse). (5) Stakeholder alignment: get agreement on scope BEFORE writing the detailed design. (6) Explicit out-of-scope: always list what's NOT included — prevents assumptions and 'while you're at it' requests. Anti-patterns: scope by committee (everyone adds their feature), gold plating (adding nice-to-haves before shipping must-haves), scope fear (cutting so much the solution doesn't solve the problem)"
+    weight: 0.30
+    description: "Scoping guide"

package/courses/technical-rfc-writing/scenarios/level-1/success-metrics.yaml

@@ -0,0 +1,43 @@
+meta:
+  id: success-metrics
+  level: 1
+  course: technical-rfc-writing
+  type: output
+  description: "Define success metrics — specify how to measure whether a proposed solution actually solves the problem it was designed to address"
+  tags: [RFC, metrics, success-criteria, measurement, KPIs, beginner]
+
+state: {}
+
+trigger: |
+  You're writing the success metrics section of an RFC. The proposal:
+  introduce a caching layer (Redis) between your API and database to
+  improve response times and reduce database load.
+
+  Current state:
+  - API p50 latency: 200ms, p99: 1.2 seconds
+  - Database CPU: 85% average during peak hours
+  - 50,000 API requests per minute at peak
+  - Database connection pool frequently exhausted (5-10 times/day)
+
+  Your first draft says: "Success: the API is faster and the database
+  is less loaded." This doesn't work — how fast? How much less? By when?
+  How do you know it actually worked?
+
+  Task: Write a success metrics section with specific, measurable
+  criteria. Include leading indicators (early signals), lagging
+  indicators (final outcomes), and how you'll measure them. Then write
+  a guide on defining success metrics for technical proposals.
+
+assertions:
+  - type: llm_judge
+    criteria: "Success metrics are specific and measurable — primary metrics with targets: (1) API latency: 'p50 latency below 50ms for cached endpoints (75% reduction). p99 latency below 300ms (75% reduction). Measured via existing APM tooling (Datadog/New Relic).' (2) Database load: 'Database CPU below 50% during peak hours (40% reduction). Zero connection pool exhaustion events per day. Measured via CloudWatch/database monitoring.' (3) Cache effectiveness: 'Cache hit rate above 85% within 2 weeks of deployment. Cache miss latency no worse than current latency (200ms p50). Measured via Redis metrics and custom instrumentation.' (4) Reliability: 'No increase in error rate (currently 0.1%). Graceful degradation to direct database queries if Redis is unavailable.' Each metric has a specific number, a measurement method, and a timeline for when the target should be reached"
+    weight: 0.35
+    description: "Specific metrics"
+  - type: llm_judge
+    criteria: "Leading and lagging indicators are distinguished — leading indicators (visible within days): cache hit rate trending upward, database connection pool utilization declining, Redis memory usage stable and within capacity. These tell you early if the solution is working. Lagging indicators (visible within weeks): sustained p99 latency improvement, database CPU reduction during peak hours, reduction in customer-reported latency complaints, cost savings from potential database downscaling. Timeline: 'Week 1: validate cache hit rate above 80% and no error rate increase. Week 2: confirm sustained latency improvement across all endpoints. Month 1: measure database CPU trend and evaluate downscaling opportunity. Month 3: full cost-benefit analysis including Redis infrastructure cost vs database savings.' Failure criteria: 'If cache hit rate is below 60% after 2 weeks, investigate cache key strategy. If p99 latency does not improve by at least 50%, the caching layer may not address the root cause'"
+    weight: 0.35
+    description: "Leading and lagging indicators"
+  - type: llm_judge
+    criteria: "Metrics guide provides reusable principles — principles: (1) Every metric needs a baseline: you can't measure improvement without knowing where you started. Capture current state before any changes. (2) Metrics should be SMART: Specific (not 'faster'), Measurable (has a number), Achievable (realistic target), Relevant (actually measures the problem), Time-bound (by when). (3) Include counter-metrics: if you optimize latency, also track error rate — fast but wrong is worse than slow but correct. (4) Distinguish vanity metrics from actionable metrics: 'cache hit rate' is actionable (you can improve key strategy), 'total requests served' is vanity (doesn't tell you if the solution works). (5) Define failure criteria: what metric values would cause you to reconsider the approach? This makes the RFC intellectually honest. (6) Automate measurement: if you can't measure it automatically, you won't measure it consistently. Set up dashboards before launch, not after. Anti-patterns: no baseline measurements, metrics that only show success (confirmation bias), metrics that require manual collection, and metrics disconnected from the original problem statement"
+    weight: 0.30
+    description: "Metrics guide"