githubnext / githubnext/gh-aw-workshop

[curriculum-eval] 05-agentic-workflows-intro.md: active_learning — conceptual intro lacks mid-page retrieval prompts

Closed Beginner friendly
#3,444 0 comments 0 reactions 0 assignees View on GitHub
curriculum documentation quality
Dominant language
JavaScript
Stars
47
Forks
19
Avg merge
8h 54m
Merged PRs (30d)
50

Description

**File:** `workshop/05-agentic-workflows-intro.md`
**Overall Score:** `5.43 / 10.0` (corpus mean: `6.14`)

**Flagged Dimensions:**

| Dimension | Score | Benchmark | Delta |
|---|---|---|---|
| cognitive_load | 8.5 / 10.0 | ≤ 800 words | word_count is 1107, −3.1 |
| active_learning | 2.4 / 10.0 | activity density ≥ 3 → 10.0 | −7.6 |
| checkpoint_quality* | 0.0 / 10.0 | present + ≥4 items → 10.0 | measurement artifact, see note |

*Note: the page has a real `## :white_check_mark: Checkpoint` with 6 checklist items — `missing_checkpoint` is a false positive from the rubric's emoji-shortcode detection bug (filed separately). This issue focuses on genuine problems: length and low active-learning density for a conceptual "understand"-level page.

**Root Cause (≤ 2 sentences):**
This is the workshop's core conceptual introduction (Bloom level: understand) explaining the trigger/task-brief/safe-outputs model and the two-file `.md`→`.lock.yml` compilation lifecycle, but it relies almost entirely on prose and two illustrative diagrams with only a single lightweight "Activity 1" prompt near the end, giving an activity density of 2.4 against a 3.0 target for 1107 words of content.

**Evidence (quoted from the file):**
> Think of it like a scheduled digest: every morning it reads your inbox and sends you a summary — no keyboard required. The agent always runs in a sandbox and posts results through guardrailed safe outputs.

This kind of extended analogy/exposition is valuable for building a mental model, but the page has only one place — the "Activity 1" prompt about opening a `.lock.yml` file — where the learner does anything other than read, which is thin for a 1107-word conceptual page positioned right before hands-on installation begins.

**Learning Science Rationale:**
Mayer's active-processing principle (part of the Cognitive-Affective Theory of Multimedia Learning) holds that learners retain conceptual material better when prompted to generate a response (predict, retrieve, apply) at multiple points rather than reading a long passage followed by a single activity at the end. Here, the "write your prediction" prompt before the two-file diagram is a good instance of this pattern, but it isn't repeated for the trigger/task-brief/safe-outputs model earlier in the page, leaving that section purely expository.

**Improvement Prompt (for an agent):**
```
Edit workshop/05-agentic-workflows-intro.md to add a second predict-then-check activity and trim length:

1. Immediately after the "Three key terms" table (Trigger, Task brief, Safe outputs), add a short
predict-then-check prompt similar in style to the existing "write your prediction" prompt used before
the two-file diagram — e.g., ask the learner to guess, before scrolling to the diagram, which of the
three terms corresponds to "the event that starts the workflow" vs "what the agent is told to do" vs
"how results get written back," then reveal the answer via the diagram/alt text immediately below.
2. Tighten the "no keyboard required" analogy paragraph and the surrounding prose by ~150-200 words to
bring word_count from ~1107 closer to the 800-word target, without removing the two diagrams.
3. Keep "Activity 1 — identify the parts" and the "## :white_check_mark: Checkpoint" section with its
6 checklist items unchanged.
4. Run `npx --yes markdownlint-cli2 "workshop/05-agentic-workflows-intro.md"` after editing.
```

**Expected Score After Fix:** `7.6 / 10.0` (after also correcting the checkpoint-detection rubric bug)

> Generated by [🔬 Curriculum Quality Evaluator](https://github.com/githubnext/gh-aw-workshop/actions/runs/35098365907) · copilot · auto · 88.8 AIC · ⌖ 13.7 AIC · ⊞ 9.5K · [◷](https://github.com/search?q=repo%3Agithubnext%2Fgh-aw-workshop+is%3Aissue+%22gh-aw-workflow-call-id%3A+githubnext%2Fgh-aw-workshop%2Fcurriculum-evaluator%22&type=issues)
> - [x] expires on Sep 17, 2026, 1:01 PM UTC

Contributor guide

No contributing guide indexed for this repository

Research direction

Edit workshop/05-agentic-workflows-intro.md, starting with the “Three key terms” table and the surrounding analogy and explanatory prose. Add the specified predict-then-check activity, trim roughly 150–200 words, and leave Activity 1 and the six-item checkpoint unchanged. Run npx --yes markdownlint-cli2 "workshop/05-agentic-workflows-intro.md"; the work is done when the page is shorter, includes the added retrieval prompt, and passes the lint check.

Written by the indexing model from the issue text.

Assessment

Tech stack
markdown
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
86/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.