Adventure: 🧪 Blind by Design — 🟢 Beginner

[aepfli]

Summary

Stand up the lab: wire the OpenFeature Java SDK + flagd contrib provider into a Spring Boot service, author the first flag, and prove hot-reload of flags.json without restarting the app.

What this PR ships

• Shared adventure infrastructure (carried by all three PRs):
  • ideas/.implemented/blind-by-design.md — the approved idea, moved to .implemented/ per the contributing guide
  • adventures/planned/00-blind-by-design/README.md
  • adventures/planned/00-blind-by-design/.gitignore
  • adventures/planned/00-blind-by-design/mkdocs.yaml
  • adventures/planned/00-blind-by-design/docs/index.md — adventure landing page; only the 🟢 Beginner card is shown at this stage. The 🟡 Intermediate and 🔴 Expert cards land with their own PRs.
• Beginner level:
  • adventures/planned/00-blind-by-design/docs/beginner.md (challenge)
  • adventures/planned/00-blind-by-design/docs/solutions/beginner.md (walkthrough — kept in repo, hidden from mkdocs.yaml nav until challenge launch)
  • adventures/planned/00-blind-by-design/beginner/ (broken-state Spring Boot project + verify.sh)
  • .devcontainer/00-blind-by-design_01-beginner/

Stacking

This is PR 1 of 3, per docs/contributing/adventures.md:160 ("ship one level at a time"):

1. 🟢 Beginner — this PR
2. 🟡 Intermediate — Adventure: 🧪 Blind by Design — 🟡 Intermediate #43
3. 🔴 Expert — Adventure: 🧪 Blind by Design — 🔴 Expert #44

Each subsequent PR adds its own level card to index.md alongside its level docs + code + devcontainer.

The original full-state PR #40 is kept open for reference and will be closed once these three land.

Part of #41

[KatharinaSick]

It's a lot of fun to play this adventure and the end result is rewarding :D It follows a bit of a different approach than the ones I created so far but that's awesome and exactly the reason I was looking forward to contributions 😊

I left a couple of comments but nothing big. Thanks for contributing again 😊

[KatharinaSick]

I just had a little conversation with Claude about the Backstory and "we" had some ideas. Feel free to take some inspiration from it, copy it, or just skip it if you want :)

Overall Story (index.md)

You are the new technical lead at the Aletheia Institute, a clinical research facility running a multi-phase vision-enhancement trial. The lab software
— a Spring Boot service — has one job: record the vision_state of every subject who passes through the protocol. The flag definitions that drive those
readings live in a flags.json file, watched by a flagd sidecar. The OpenFeature SDK is supposed to call that sidecar on every evaluation.

Supposed to.

The previous engineer left without finishing the integration. For the past eight months, every subject through the door has received the same hard-coded label: "untreated". The lab director assumed the system was reading the chart. It wasn't reading anything.

That's bad. But it isn't the crisis.

Phase 3 is the crisis.

Eight weeks ago, the Institute began its flagship trial: a new amplifier variant, delivered to a fractional cohort via a targeting rule in flags.json. The dashboard that should be tracking outcomes has never come online — the metric exporter was never wired up. Four adverse-event reports have been filed. In each one, the subject's vision_state at discharge was worse than at enrollment.

No one can see what's happening. The monitoring is dark — not by accident, but because no one ever turned the lights on.

Your mission across three levels: stand up the lab so it reads the chart, layer in evaluation context so outcomes can be tracked by cohort, then wire up the observability stack, find the misbehaving Phase 3 variant in the dashboard, and roll it back before the director signs off on the next enrollment batch.

Beginner

You arrived at the Aletheia Institute this morning. Your key card still has temporary clearance printed on it in red. The previous technical lead — whose name you keep seeing in commit messages — cleared out their desk three weeks ago, no documentation, no handoff, no answers.

What they left behind: a Spring Boot service on :8080 that is supposed to record the vision_state of every subject who passes through the protocol. A flagd sidecar on :8013 that is supposed to serve those readings from flags.json. And a pom.xml with no OpenFeature dependencies in it at all.

The lab is taking readings. Every reading says "untreated". It has been saying that for eight months.

Your mission: wire the OpenFeature SDK into the service so the lab actually reads the chart, author the vision_state flag in flags.json, and prove that the lab can change what it records — without restarting anything — before the next subject is enrolled.

[aepfli]

Thank you for the editorial care here — and honestly, running it through Claude first is exactly the kind of pre-work that makes a suggestion easy to engage with, because the voice and the structure are already aligned enough that I can read it as a draft rather than a sketch. The three pieces doing the most work in your draft, to my eye, are: the Aletheia Institute as the place — the Greek pun on truth/disclosure lands the vision theme more cleanly than "a research lab" ever did; the eight-months / eight-weeks timeline, which makes the stakes concrete instead of abstract; and the "the monitoring is dark — not by accident, but because no one ever turned the lights on" sentence, which is the one line in the draft that explicitly previews the Expert-level resolution.

I have cherry-picked those three into docs/index.md on the Beginner branch in 222b1d0; the rebase has cascaded the change through Intermediate and Expert, so the framing now appears once at the top of the adventure rather than being repeated per level. The Beginner-level cinematic intro (the "your key card still has temporary clearance printed on it" opening) I have left out — the most recent round of trimming on the level intro was deliberate, and the cinematic version doubles the story length in exactly the section I had just decided to keep brief.

That said, the key-card opening is genuinely strong on its own merits, and if you would rather see it kept somewhere — perhaps as an optional "🎬 Set the scene" callout that participants can fold open — I am happy to revisit. Push back any time.

[aepfli]

The Intermediate / Expert stub docs and their landing-page cards are out of this PR now. They were only ever there to keep docs/index.md links from 404'ing — once the nav was trimmed, the cards on the page were the only thing still pointing at those files, and that's needless noise on a Beginner-only PR.

From here, each level's card and level-doc travel together: Intermediate gets its card + intermediate.md in #43, Expert gets its card + expert.md in #44. Both are rebased on top of this branch.

[KatharinaSick]

made some minor adjustments but looks great - thank you! 😊