Skip to content

[workshop-sim] Improve: Strengthen value proposition and add env self-check to steps 0–1 #231

Description

@github-actions

Problem

Steps 0 (Welcome, 13.2%), 1 (Prerequisites, 12.1%), and 2 (Setup, 17.2%) together eliminate 14 of 38 students before they ever reach the substantive content. The Welcome step does not immediately convey value to skeptical or impatient readers, and the Prerequisites step does not include live environment-validation commands — meaning students discover missing tools (unauthenticated gh, missing node, wrong OS) much later at step 6, causing abandonment.

Simulation pain points: "Value proposition not convincingly stated" (3 students), "No prior CLI experience — unfamiliar with terminal commands" (7 students, most failing at steps 0–2).

Proposed Change

  1. 00-welcome.md — Add a 2–3 sentence "Why this matters" paragraph in the first 10 lines with a concrete outcome statement (e.g., "By the end you'll have a scheduled AI agent that posts a daily summary of your repository's activity — automatically, no manual check required").
  2. 01-prerequisites.md — Add a self-check script block near the top:
    gh auth status && gh --version && echo "✅ Ready to continue"
    If the command fails, link directly to the auth fix steps. This catches the most common failure mode before step 6.

Acceptance Criteria

  • 00-welcome.md opens with a concrete outcome statement within the first visible paragraph
  • 01-prerequisites.md includes a single copy-paste self-check command that validates gh auth and version
  • Self-check block links to gh auth login documentation if the command fails
  • npx markdownlint-cli2 "workshop/00-welcome.md" "workshop/01-prerequisites.md" passes

Suggested Owner

workshop maintainer (light copy + one code block addition)

Generated by 🔬 Workshop Student Simulator · 39 AIC · ⌖ 5.8 AIC · ⊞ 8K ·

Metadata

Metadata

Type

No type

Fields

No fields configured for issues without a type.

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions