Contributing a case

The case library grows when facilitators and graduates turn real decisions into practice. A good case takes an hour or two to write and gets used by every cohort after that.

How to write a case

1. Copy templates/case-template.md into the folder for its type under src/content/cases/: incidents/, prs/, designs/, calibration/, or katas/. Name the file after the case, in lowercase with hyphens, for example retry-storm-after-failover.md.
2. Fill in the frontmatter. The build checks every field, so npm run build tells you exactly what’s missing.
3. Write the body sections as H2 headings, in this order:
   • ## Setup: the context the learner sees first.
   • ## Stages (incidents only): one H3 per stage. Each stage is revealed separately, and the learner writes what they’d check next before the next one unlocks.
   • ## Outcome: what actually happened. Hidden until the learner commits.
   • ## Senior commentary: how an experienced engineer reasoned through it.
   • ## Discussion questions
   • ## Answer key (PR cases only): every planted flaw, with a severity of high, medium, or low. PR cases also put the diff in a fenced diff block inside Setup.
4. Run npm run check:cases and npm run build, then open the case with npm run dev and work through it once as a learner.
5. Open a pull request. A facilitator reviews it against the quality bar below.

Anonymization checklist

Every case derived from internal material must pass this checklist before anonymized: true is set. CI fails any internal case with anonymized: false.

• Remove all personal names, usernames, and emails.
• Remove internal hostnames, service names, customer names, and URLs.
• Change numbers enough that they don’t identify the system, while keeping the shape of the problem.
• Write in blameless language: describe decisions and conditions, not people’s mistakes.
• Get approval before publishing anything derived from internal material externally.

Quality bar

Quality bar for a case: it has a clear point where the learner must commit, a known outcome to reveal, and an answer that’s defensible but not obvious. If smart engineers would split roughly 50/50 before the reveal, it’s a good case.

A few more things reviewers look for:

• No hindsight in the setup. Give learners only what the people involved knew at the time.
• The numbers matter. Include the numbers that decide the outcome, and leave out ones that don’t.
• The commentary shows process. It should say which signals the senior engineer looked at and why, not just restate the outcome.

Replacing example cases

The 10 cases marked draft: true show an “Example case” badge. They’re generic placeholders that show the format. Replace them with real cases as the library grows: delete the placeholder once a real case of the same type covers its week.

The case template

Copy this into a new file under src/content/cases/<type>/:

---
title: "A short, specific title"
type: incident        # incident | pr | design | calibration | kata
week: 5               # 1–8: the week this case supports
topics: [caching, retries]
difficulty: 2         # 1 introductory · 2 intermediate · 3 advanced
ai_allowed: false     # can learners use AI after committing?
source: internal      # internal | public
source_url: ""        # required if source is public
anonymized: true      # must be true for internal cases
prompt: "The one question the learner commits an answer to."
answer_type: free_text   # free_text | multiple_choice | numeric
choices: []              # for multiple_choice: at least two options
draft: false
---

## Setup

What the learner sees first: the system, the constraints, and the numbers that matter.
Include only what the people involved knew at the time. No hindsight.

PR cases: put the diff here in a fenced block that starts with ```diff.

## Stages

Incidents only (delete this section for other types). Each H3 is revealed one at a
time, and the learner must write what they'd check next before the next one unlocks.

### Stage 1: The alert

What the on-call engineer could see: alerts, graphs, log lines.

### Stage 2: The next clue

What they found next.

## Outcome

What actually happened, hidden until the learner commits. Start with the answer in
bold, then explain why.

## Senior commentary

How an experienced engineer reasoned through it, in their own voice. Focus on which
signals they looked at and why, not just the answer.

## Discussion questions

1. A question about the reasoning, not just the answer.
2. A question that connects the case to the learner's own work.

## Answer key

PR cases only (delete this section for other types). List every planted flaw with
a severity.

| # | Flaw | Severity |
| --- | --- | --- |
| 1 | **Short name.** What's wrong and why it matters. | High |