Create Learning Module

Outputs

Execution Phases

Phase 1: Setup

Create the module branch and establish the working context.

QMD Context Bootstrapping

Before starting, search qmd for prior module patterns (skip if qmd unavailable):

1. Run qmd query "learning module {module_topic}" -C 38 --json --limit 3 -c skill-artifacts

2. If results with score > 50%, read top docs with qmd get for reusable structure

3. Incorporate as prior-art context (do not skip phases)

4. Confirm inputs with the facilitator:

   • Module number, topic, learning objective
   • What artifact type students will build
   • Any prerequisites from previous modules

5. Create the git branch:

   cd {repo_path}
   git checkout main
   git checkout -b module-{N}/start
   

6. Confirm the facilitator worktree exists:

   ls {facilitator_worktree}/facilitator/modules/
   

   If missing, create it:

   git worktree add {facilitator_worktree} -b facilitator main
   mkdir -p {facilitator_worktree}/facilitator/modules
   

7. Initialize the facilitator guide with the header:

   # Module {N}: {Topic} -- Facilitator Guide
   
   ## Overview
   - Duration: ~{X} minutes
   - Outcome: {learning_objective}
   - Branch: `module-{N}/start` (students work here), `module-{N}/solution` (reference)
   - Prerequisite: {prerequisites}
   
   ## Key Concepts to Teach
   {numbered list of 5-7 concepts}
   
   ## Sad Paths (Instructor Gotchas)
   {populated during walkthrough -- start empty}
   
   ---
   
   ## Steps
   

8. Ask the facilitator: "Ready to start the walkthrough? I'll guide you section by section. Say 'keep', 'cut', or 'revise' for each proposal. Say 'capture' when you want to write a facilitator guide step."

Phase 2: Walk Through as Student

The core learning loop. The facilitator acts as a student while the skill acts as instructor.

For each section of the artifact:

1. Propose content. Present one section at a time with reasoning.

2. Wait for approval. The facilitator responds:

   • "keep" -- Accept the section, add it to the artifact file
   • "cut" -- Remove it, explain why, propose alternative
   • "revise" -- Modify based on feedback, re-propose
   • "capture" -- Write the current section as a facilitator guide step, then continue

3. Write to the artifact file. After approval, append to the exercise artifact at:

   {repo_path}/.github/{artifact_type}s/{artifact_filename}
   

   (Adjust path based on artifact_type: agents/ for agents, skills/ for skills, hooks/ for hooks)

4. Track mistakes. When the instructor (skill) makes an error and the facilitator catches it, log it as a Sad Path. These become teaching material.

5. Validate with references. After completing each major section, use the reference skill to verify claims:

   Use the {reference_skill} skill to validate {section_name}
   

Interaction rules during walkthrough:

• Propose one section at a time -- never dump the whole artifact
• Explain WHY each section exists, not just WHAT it contains
• Ask conceptual questions before proposing ("Should a verifier edit code?")
• When the facilitator says something is wrong, research and correct -- don't defend

Phase 3: Capture Facilitator Guide

When the facilitator says "capture", write a numbered Step to the facilitator guide.

Step template:

### Step {N}: {Section Name} (~{X} min)

{Context for the facilitator -- what this step teaches and why}

**Facilitator says:**
> "{Opening line to say to students}"

**Teaching approach:** {How to guide students through this section}

**Students add:**
```{language}
{The content students should write}

Key teaching moment:

"{The core insight this step delivers}"

Sad path: {Mistakes the instructor made or common student mistakes}

Step {N} Checkpoint

• {Verification item 1}
• {Verification item 2}
• {Verification item 3}

**Rules for capture:**
- Include any sad paths that occurred during the walkthrough for this section
- Include teaching moments and discussion prompts that emerged
- Reference the actual content from the artifact (not paraphrased)
- Add timing estimates based on complexity (simple: ~3 min, moderate: ~5 min, complex: ~10 min)

After writing each step, sync to the facilitator worktree:
```bash
cp {session_file} {facilitator_worktree}/facilitator/modules/MODULE_{N}_{TOPIC}.md

Phase 4: Build Help Agent

After completing the walkthrough and all capture steps, create a module-specific help agent.

1. Invoke the create-agent skill with these parameters:

   • Name: module-{N}-help
   • Description: Assists Module {N} workshop students building {artifact_type} by reading their work and providing conceptual guidance
   • Model: Claude Opus 4.6 (copilot) -- high reasoning for adaptive learning styles
   • Tools: [read, search] -- read-only, never edit
   • Behavior: Socratic -- questions not answers, examples only when completely stuck
   • Curriculum: Embed the module's step sequence from the facilitator guide
   • Common mistakes: Derive from sad paths documented during walkthrough

2. Commit to main so students have it from the start:

   git checkout main
   git add .github/agents/module-{N}-help.agent.md
   git commit -m "Add Module {N} help agent for student assistance"
   git checkout module-{N}/start
   git rebase main
   

Phase 5: Test and Tighten

Test the completed artifact against the real application.

1. Invoke the artifact:

   • For agents: Use /agent {name} or --agent={name} with a realistic prompt
   • For skills: Trigger the skill with a relevant task
   • For hooks: Trigger the lifecycle event the hook responds to

2. Evaluate the output:

   • Does it follow the spec written in the artifact?
   • Where does it deviate?
   • Is the deviation an improvement or a problem?

3. Tighten the spec based on what the artifact actually produced:

   • Update sections that were too loose
   • Add structure that the artifact naturally produced but wasn't specified
   • Document deviations as classroom discussion points

4. Re-capture any steps that changed during tightening.

Phase 6: Student Guide

Create or update the student-facing workshop guide with a section for this module.

1. Check if docs/WORKSHOP_GUIDE.md exists on main:

   git checkout main
   ls docs/WORKSHOP_GUIDE.md
   

   If it does not exist, create it with a setup section (prerequisites, repo clone, verification commands) and a workshop overview table.

2. Add a module section with these elements:

   • Module title and objective (one sentence: what the student will be able to do)
   • "What you will learn" -- 4-6 bullet points, high-level concepts only
   • Getting started command: git checkout module-{N}/start
   • What they will find on the branch (starting state)
   • What they will create (artifact path and name)
   • One-line description of the facilitator-led flow (do NOT include step-by-step instructions -- the facilitator guides them live)
   • Help agent reference: "If you get stuck, invoke module-{N}-help"
   • Solution reference: git checkout module-{N}/solution

3. Update the overview table at the top of the guide to include the new module row.

4. Commit to main:

   git add docs/WORKSHOP_GUIDE.md
   git commit -m "Add Module {N} to student workshop guide"
   

Rules for student guides:

• Keep it high-level. Students should know WHAT they are building and WHY, not HOW step-by-step.
• The facilitator guide has the detailed steps. The student guide has the map.
• Do not include facilitator coaching notes, sad paths, or timing information.
• Do not include exercise answers or solution code.
• Include help agent and solution branch references so students can self-serve when stuck.

Phase 7: Git Finalization

Set up the complete branch structure.

1. Create the solution branch:

   git checkout module-{N}/start
   git checkout -b module-{N}/solution
   git add .github/{artifact_type}s/{artifact_filename}
   git commit -m "Add completed {artifact_filename} (Module {N} solution)"
   

2. Ensure main has help agents and reference materials:

   git checkout main
   # Verify help agent is committed
   git log --oneline -1 -- .github/agents/module-{N}-help.agent.md
   

3. Sync facilitator worktree:

   cp {session_facilitator_guide} {facilitator_worktree}/facilitator/modules/MODULE_{N}_{TOPIC}.md
   

4. Verify branch structure:

   Branch	Contains	Audience
   main	App + all help agents + reference materials	Students
   module-{N}/start	main content, exercise artifact untracked	Students
   module-{N}/solution	Completed artifact committed	Students (post-exercise)
   facilitator	main + facilitator/ directory	Facilitator only

5. Print summary:

   === Module {N}: {Topic} Complete ===
   Artifact: {artifact_filename} ({line_count} lines)
   Facilitator guide: MODULE_{N}_{TOPIC}.md ({step_count} steps)
   Student guide: docs/WORKSHOP_GUIDE.md (Module {N} section added)
   Help agent: module-{N}-help.agent.md
   Branches: module-{N}/start, module-{N}/solution
   Sad paths documented: {count}
   

Facilitator Guide Structure

Every module's facilitator guide follows this structure:

# Module {N}: {Topic} -- Facilitator Guide

## Overview
- Duration, outcome, branches, prerequisites

## Key Concepts to Teach
- Numbered list of 5-7 core concepts

## Sad Paths (Instructor Gotchas)
- Numbered list of real mistakes from the walkthrough

---

## Steps

### Step 1: {First Section} (~X min)
{Step template as defined in Phase 3}

### Step 2: {Second Section} (~X min)
...

### Step N: Invoke and Test (~5 min)
{Always the final content step}

---

## Facilitator Notes
- Timing tips
- Discussion prompts
- Early finisher challenges
- What to defer to later modules

Guardrails

• Never skip the student walkthrough (Phase 2). The process IS the product.
• Never write the complete artifact upfront and explain it after. Build incrementally.
• Never fabricate sad paths. Only document mistakes that actually happened.
• Always validate with official reference docs before finalizing content.
• Always test the artifact before marking the module complete.
• Never commit the exercise artifact to module-N/start. It must be untracked (students build it).
• Always commit the help agent to main (students need it before starting).
• Never use emojis in any generated content.

Validation Checklist

Before marking a module complete:

• Exercise artifact builds/runs correctly
• Facilitator guide has all steps with checkpoints
• Student guide section added to docs/WORKSHOP_GUIDE.md
• Help agent reads student work and guides without answering
• Artifact tested against real application
• Spec tightened based on test results
• module-N/start branch exists (artifact untracked)
• module-N/solution branch exists (artifact committed)
• Help agent committed to main
• Student guide committed to main
• Facilitator guide synced to worktree
• Sad paths documented from actual walkthrough mistakes
• No emojis in any files

Artifact Persistence

After generating output files, persist to qmd for cross-session retrieval:

1. Copy facilitator guides and exercise artifacts to ~/.copilot/kb-export/skill-artifacts/create-learning-module/<date>/
2. Run qmd update in background (best-effort, skip silently if qmd unavailable)