off-on-dev · sinduri-g · Apr 1, 2026 · Mar 30, 2026 · Mar 30, 2026
diff --git a/docs/contributing/adventure-ideas.md b/docs/contributing/adventure-ideas.md
@@ -16,9 +16,13 @@ adventure could look like and what learners would gain from it.
 
 ## How to Submit
 
-1. **Copy** `ideas/adventure-idea-template.md` and rename it to `ideas/your-adventure-name.md`
-2. **Fill in the template** — replace all placeholders with your idea
-3. **[Open a pull request](https://github.com/dynatrace-oss/open-ecosystem-challenges/compare)** with the title `Adventure Idea: [emoji] Your Adventure Name`
+1. **Fork** the repository on GitHub
+2. **Copy** `ideas/adventure-idea-template.md` and rename it to `ideas/your-adventure-name.md`:
+   ```
+   cp ideas/adventure-idea-template.md ideas/your-adventure-name.md
+   ```
+3. **Fill in the template** and commit your changes
+4. **[Open a pull request](https://github.com/dynatrace-oss/open-ecosystem-challenges/compare)** with the title `Adventure Idea: [emoji] Your Adventure Name`
 
 No issue required. Submit your idea directly as a PR.
 
@@ -57,43 +61,47 @@ Strong adventure ideas share these qualities:
 
 ## Calibrating Difficulty
 
-The 🟢 Beginner / 🟡 Intermediate / 🔴 Expert labels set participant expectations before they start. Getting this right matters — a mislabeled level is frustrating regardless of which direction it's off.
+The 🟢 Beginner / 🟡 Intermediate / 🔴 Expert labels set participant expectations before they start. Getting this right matters - a mislabeled level is frustrating regardless of which direction it's off.
 
 Three levels are recommended but not required. A single well-scoped level or a two-level adventure is perfectly valid.
 
 ### What each level feels like
 
-**🟢 Beginner** — Get to know the tool. Participants encounter it for the first time and learn the fundamentals: what it does, how it's configured, and what "working" looks like. The challenge is contained and approachable.
+**🟢 Beginner** - Get to know the tool. Participants encounter it for the first time and learn the fundamentals: what it does, how it's configured, and what "working" looks like. The challenge is contained and approachable.
 
-**🟡 Intermediate** — Move into systems thinking. Participants have seen the tool before; now they see how it fits into a broader, more realistic setup. The interesting part is the integration — how things connect, interact, and break in non-obvious ways.
+**🟡 Intermediate** - Move into systems thinking. Participants have seen the tool before; now they see how it fits into a broader, more realistic setup. The interesting part is the integration - how things connect, interact, and break in non-obvious ways.
 
-**🔴 Expert** — Something genuinely interesting. Not just "harder" — a qualitatively different challenge that rewards deep understanding. Adventure 01 is the best example: Expert isn't just more configuration, it's a completely different observability layer that ties everything together.
+**🔴 Expert** - Something genuinely interesting. Not just "harder" - a qualitatively different challenge that rewards deep understanding. Adventure 01 is the best example: Expert isn't just more configuration, it's a completely different observability layer that ties everything together.
 
 ### A quick self-check
 
 Ask: *Could someone who has read the docs but never used this tool in a real project solve this in under an hour?*
 
 - **Yes** → Beginner
-- **No — they'd need to understand how two systems interact** → Intermediate
-- **No — they'd need to understand the full architecture** → Expert
+- **No - they'd need to understand how two systems interact** → Intermediate
+- **No - they'd need to understand the full architecture** → Expert
 
 ### One level, a few new concepts
 
-A common mistake is packing too much into a single level. Each level should introduce 2–3 new ideas — not a tour of everything the technology can do.
+A common mistake is packing too much into a single level. Each level should introduce 2–3 new ideas - not a tour of everything the technology can do.
 
 Adventure 01 is a useful reference: Beginner introduces Argo CD ApplicationSets → Intermediate adds Argo Rollouts and PromQL → Expert adds OpenTelemetry Collector and distributed tracing.
 
 ## Adventure Idea Template
 
 A ready-to-use template is available at [`ideas/adventure-idea-template.md`](https://github.com/dynatrace-oss/open-ecosystem-challenges/blob/main/ideas/adventure-idea-template.md).
 
-Copy it, rename it to `ideas/your-adventure-name.md`, and fill in the placeholders. The three-level format is recommended but not required — adjust based on your idea.
+Copy it using the command below, fill in the placeholders, and follow the [How to Submit](#how-to-submit) steps above.
+
+```
+cp ideas/adventure-idea-template.md ideas/your-adventure-name.md
+```
 
 See [Echoes Lost in Orbit](https://github.com/dynatrace-oss/open-ecosystem-challenges/blob/main/ideas/.implemented/echoes-lost-in-orbit.md) for a complete example of a well-written idea.
 
 ## Writing Good Objectives
 
-Objectives are verifiable outcomes, not tasks. Write them as the state a participant should reach, not the steps they should follow — specific enough that the verification script can check them directly.
+Objectives are verifiable outcomes, not tasks. Write them as the state a participant should reach, not the steps they should follow - specific enough that the verification script can check them directly.
 
 | Task (avoid) | Outcome (aim for) |
 |---|---|

diff --git a/ideas/.implemented/echoes-lost-in-orbit.md b/ideas/.implemented/echoes-lost-in-orbit.md
@@ -12,18 +12,16 @@
 
 **Technologies:** Argo CD, Argo Rollouts, OpenTelemetry, Prometheus, Jaeger, Kubernetes
 
-**Levels:**
-
-- 🟢 Beginner: Fix a broken multi-environment GitOps setup
-- 🟡 Intermediate: Stabilize a failing canary rollout with metrics-based analysis
-- 🔴 Expert: Build an observability pipeline to validate traffic before promoting releases
-
 ---
 
 ## Levels
 
 ### 🟢 Beginner: Broken Echoes
 
+#### Description
+
+Fix a broken multi-environment GitOps setup
+
 #### Story
 
 The Echo Server is misbehaving. Both environments (`staging` and `production`) seem to be down, and messages are silent. The previous engineer left a note saying "I tried to set up this fancy ApplicationSet thing to deploy to both environments at once, but now nothing works."
@@ -58,6 +56,10 @@ By the end of this level, the learner should:
 
 ### 🟡 Intermediate: The Silent Canary
 
+#### Description
+
+Stabilize a failing canary rollout with metrics-based analysis
+
 #### Story
 
 After fixing the communication outage, the Intergalactic Union welcomed a new species: the Zephyrians. The communications team attempted to deploy their language files using a progressive delivery system, but the rollout is failing. The Zephyrians are still waiting to communicate with the rest of the galaxy.
@@ -93,6 +95,10 @@ By the end of this level, the learner should:
 
 ### 🔴 Expert: Hyperspace Operations & Transport
 
+#### Description
+
+Build an observability pipeline to validate traffic before promoting releases
+
 #### Story
 
 Word of your progressive release mastery spread across the galaxy. The Bytari, a highly advanced species from the Andromeda sector, want to apply progressive delivery to their mission-critical service: HotROD (Hyperspace Operations & Transport - Rapid Orbital Dispatch), an interstellar ride-sharing service handling dispatch requests across thousands of star systems.

diff --git a/ideas/adventure-idea-template.md b/ideas/adventure-idea-template.md
@@ -1,29 +1,91 @@
 # Adventure Idea: [emoji] [Your Adventure Name]
 
+<!-- =========================================================================
+  HOW TO USE THIS TEMPLATE
+  =========================================================================
+  1. Fork the repository on GitHub.
+  2. Copy this file:
+        cp ideas/adventure-idea-template.md ideas/your-adventure-name.md
+  3. Replace every [bracketed placeholder] with your content.
+     Keep all formatting (headings, bold labels, etc.) exactly as they appear.
+  4. Remove all HTML comments.
+  5. Commit your changes and open a pull request with the title:
+        Adventure Idea: [emoji] Your Adventure Name
+  ========================================================================= -->
+
 ## Overview
 
-**Theme:** [2-3 sentences describing the scenario and what's at stake. Who is the learner in this story?]
+<!-- Set up the scenario: who is the learner, what went wrong, what's at stake.
+     Example: "You're a platform engineer at a fast-growing startup. A bad deploy
+     just took down production. Roll back fast and put guardrails in place." -->
+
+**Theme:** [2-3 sentences describing the scenario and what's at stake]
+
+<!-- What learners will DO, not which tools they use.
+     Good: "Release safely using progressive delivery"
+     Avoid: "Use Argo Rollouts" -->
 
 **Skills:**
 
 - [Action-oriented skill 1, e.g., "Deploy reliably across multiple environments"]
 - [Action-oriented skill 2]
 - [Action-oriented skill 3]
 
-**Technologies:** [Tools involved, e.g., Argo CD, Kubernetes, Prometheus]
-
-**Levels:**
+<!-- Comma-separated. Only include tools participants directly use. -->
 
-- 🟢 Beginner: [One-liner description]
-- 🟡 Intermediate: [One-liner description]
-- 🔴 Expert: [One-liner description]
+**Technologies:** [Tools involved, e.g., Argo CD, Kubernetes, Prometheus]
 
 ---
 
 ## Levels
 
+<!-- =========================================================================
+  Each level is a standalone challenge. Include Beginner, Intermediate,
+  and/or Expert - delete any you don't need.
+
+  DIFFICULTY GUIDE:
+    🟢 Beginner - First encounter. Solvable in under an hour with just the docs.
+    🟡 Intermediate - Has used the tool before. Integration and non-obvious failure modes.
+    🔴 Expert - Qualitatively harder. Requires deep architectural understanding.
+
+  SECTION GUIDE - each level needs all six #### sections:
+
+  #### Description
+    One sentence summarizing what the participant does.
+    Example: "Diagnose a broken Argo CD sync and restore a failing deployment."
+
+  #### Story
+    Set the scene: who the participant is, what broke, what they need to fix.
+    One to two paragraphs.
+    Example: "The overnight deploy silently failed. You're the on-call engineer -
+    the dashboard is red and the team is waiting."
+
+  #### The Problem
+    For the implementer only - never shown to participants.
+    Describe exactly what to break or misconfigure in the challenge environment.
+    Example: "The ApplicationSet generator uses the wrong path template,
+    causing it to generate zero Applications."
+
+  #### Objective
+    Describe what success looks like, not what steps to take.
+    Good:  "Two Applications appear in the Argo CD dashboard with Synced status"
+    Avoid: "Fix the ApplicationSet"
+
+  #### What You'll Learn
+    2-3 concepts they'll understand after completing this level.
+    Example: "How Argo CD sync waves control rollout order"
+
+  #### Tools & Infrastructure
+    Tools: what they run commands against.
+    Infrastructure: what must be running in the environment.
+  ========================================================================= -->
+
 ### 🟢 Beginner: [Level Name]
 
+#### Description
+
+[One sentence describing what the participant will do in this level]
+
 #### Story
 
 [Brief narrative setup for this level]
@@ -55,6 +117,10 @@ By the end of this level, the learner should:
 
 ### 🟡 Intermediate: [Level Name]
 
+#### Description
+
+[One sentence describing what the participant will do in this level]
+
 #### Story
 
 [Brief narrative setup for this level]
@@ -86,6 +152,10 @@ By the end of this level, the learner should:
 
 ### 🔴 Expert: [Level Name]
 
+#### Description
+
+[One sentence describing what the participant will do in this level]
+
 #### Story
 
 [Brief narrative setup for this level]

diff --git a/scripts/new-adventure.sh b/scripts/new-adventure.sh
@@ -107,7 +107,11 @@ extract_level_section() {
   ' "$selected_file"
 }
 
-level_summary=$(grep "^- $level_emoji $level_difficulty:" "$selected_file" | sed "s/^- $level_emoji [^:]*: //")
+level_summary=$(awk -v level="$selected_level" '
+  /^### / { in_level = ($0 == "### " level); next }
+  in_level && /^#### Description/ { in_desc = 1; next }
+  in_desc && NF > 0 { print; exit }
+' "$selected_file")
 level_story=$(extract_level_section "Story")
 level_objective=$(extract_level_section "Objective")
 level_learnings=$(extract_level_section "What You'll Learn")