Facilitator Guide

Open Source Assistive Technology Hackathon

This document is for workshop facilitators only. Participants should start with README.md and docs/00-pre-workshop-setup.md.

** If you're looking for Challenge Management (issue generation, monitoring, bot setup): See FACILITATOR_CHALLENGES.md**

Quick Reference Timeline

Skip to your current phase:

Phase 1: Setup (2 weeks before)

Phase 2: Launch (1 week before)

Phase 3: Day 1 (30 min before session)

Phase 4: Day 1 Session - Saturday, March 7, 2026 (7.5 hours)

Phase 5: Day 2 Morning (30 min before session)

Phase 6: Day 2 Session - Sunday, March 8, 2026 (7.5 hours)

Phase 7: Post-Workshop

Full Details

(See sections below for complete instructions on each phase)

Repository Structure

This is the single repository students clone. Everything they need for both days is here:

learning-room/                  ← workshop repository root
├── README.md                   ← participant-facing start page
├── CONTRIBUTING.md             ← contribution guide
├── CODE_OF_CONDUCT.md          ← community standards
├── FACILITATOR.md              ← this file
├── .gitignore
├── .github/
│   ├── ISSUE_TEMPLATE/
│   │   ├── config.yml          ← disables blank issues, links to Skills modules
│   │   ├── accessibility-bug.yml ← accessibility bug report YAML form
│   │   └── feature-request.yml ← feature/improvement request YAML form
│   ├── PULL_REQUEST_TEMPLATE.md ← PR template with accessibility checklist
│   ├── agents/                 ← Accessibility Agents - 55 Copilot agents across 3 teams
│   │   ├── daily-briefing.agent.md
│   │   ├── issue-tracker.agent.md
│   │   ├── pr-review.agent.md
│   │   ├── analytics.agent.md
│   │   ├── insiders-a11y-tracker.agent.md
│   │   ├── template-builder.agent.md
│   │   └── preferences.example.md
│   └── prompts/                ← 54+ slash commands for Copilot Chat
│       ├── a11y-update.prompt.md
│       ├── create-issue.prompt.md
│       ├── daily-briefing.prompt.md
│       ├── explain-code.prompt.md
│       ├── review-pr.prompt.md
│       ├── triage.prompt.md
│       └── ... (48 more - see docs/appendix-v-accessibility-agents-reference.md)
├── docs/                       ← full workshop curriculum (17 chapters + appendices A-Z)
│   ├── 00-pre-workshop-setup.md
│   ├── 01-understanding-github-web-structure.md
│   ├── 02-navigating-repositories.md
│   ├── 03-the-learning-room.md
│   ├── 04-working-with-issues.md
│   ├── 05-vscode-accessibility.md
│   ├── 06-working-with-pull-requests.md
│   ├── 07-merge-conflicts.md
│   ├── 08-culture-etiquette.md
│   ├── 09-labels-milestones-projects.md
│   ├── 10-notifications.md
│   ├── 11-git-source-control.md
│   ├── 12-github-pull-requests-extension.md
│   ├── 13-github-copilot.md
│   ├── 14-accessible-code-review.md
│   ├── 15-issue-templates.md
│   ├── 16-accessibility-agents.md
│   ├── appendix-a-glossary.md              ← every term explained
│   ├── appendix-b-screen-reader-cheatsheet.md ← full shortcut reference
│   ├── appendix-c through appendix-x      ← deep-dive references (C-X)
│   └── (see appendix-u-resources.md for complete file listing)
└── learning-room/              ← practice content (contribution sprint targets)
    ├── README.md
    └── docs/
        ├── welcome.md          ← has [TODO] gaps for participants to complete
        ├── keyboard-shortcuts.md ← has intentional errors and a heading hierarchy problem
        └── setup-guide.md      ← has a broken URL and [TODO] markers

Two Weeks Before the Workshop

Create the GitHub Organization and Repository

  1. Create a GitHub org (recommended) or use your personal account
  2. Create a new repository named learning-room (or your preferred name)
  3. Make it Public - participants need read access without being org members
  4. Push the contents of this repository to it:
    git remote add origin https://github.com/[org]/learning-room
git push -u origin main

Configure the Repository

Enable Issues: Settings → Features → check Issues

Enable Discussions (optional): Settings → Features → check Discussions (useful for async Q&A)

Branch protection for main: Settings → Branches → Add rule:

Mark as Template Repository (recommended): Settings → check "Template repository" This allows you to create a fresh copy for each cohort with one click.

One Week Before the Workshop

Create Labels

Navigate to Issues → Labels → create these labels (delete GitHub defaults if desired):

Label Color Description
accessibility #0075ca Keyboard, screen reader, WCAG
good first issue #7057ff Good for new contributors
documentation #0075ca Improvements to docs
needs triage #e4e669 Awaiting review by a maintainer
bug #d73a4a Something isn't working
enhancement #a2eeef New feature or request
help wanted #008672 Extra attention needed
question #d876e3 More information needed
wontfix #ffffff This will not be addressed
duplicate #cfd3d7 This issue already exists

Create a Milestone

Issues → Milestones → New milestone:

Pre-Seed Issues for the Contribution Sprint

Create one issue per participant, assigned to them. Each issue points to a specific problem in learning-room/docs/. Template:

Issue title: Fix: [specific problem] in [filename] Issue body:

## What to Fix

[Specific description of the problem - be precise enough that the participant knows exactly
what line or section to look at.]

## File to Edit

`learning-room/docs/[filename].md`

## Acceptance Criteria

- [ ] [Specific thing that should be true when the fix is complete]
- [ ] No new heading-level skips introduced
- [ ] Link text is descriptive (not "click here")

## How to Contribute

See [Working with Issues](docs/04-working-with-issues.md) and the [Day 1 Agenda](DAY1_AGENDA.md) for the full contribution workflow.

Pre-seeded issues to create (by file):

File Problem to fix Label
keyboard-shortcuts.md Heading jumps from # (h1) to #### (h4) for NVDA section sub-headings - should be ## and ### accessibility, good first issue
keyboard-shortcuts.md The Accessibility Settings link is broken: htps:// has a typo bug, good first issue
setup-guide.md Step 2 link has a typo: htps://github.com/settings/accessibility - missing one t bug, good first issue
setup-guide.md "Note: Links marked [TODO]" callout at the bottom - replace with actual links to the workshop repo documentation, good first issue
welcome.md Last reviewed: [DATE] placeholder at the bottom - replace with today's date (format: YYYY-MM-DD) documentation, good first issue
welcome.md [TODO] paragraph about who can contribute (line 22) documentation, good first issue
welcome.md [TODO] paragraph about reading an issue to decide if it's right for you (line 40) documentation, good first issue
welcome.md [TODO] sentence about what a merged PR means for GitHub profile (line 52) documentation, good first issue

Create extras for any additional participants.

Create the Welcome Issue

Create this issue, unassigned, labeled good first issue:

Title: Welcome! Introduce yourself Body:

Welcome to the workshop repository! This issue is for introductions.

## How to participate

Leave a comment on this issue introducing yourself:

- Your name (first name or preferred name)
- Your screen reader and operating system
- One thing you are hoping to learn or do during this workshop

Use Markdown in your comment:
- Use `**bold**` to highlight your screen reader name
- Use a task list (`- [ ]`) for things you want to accomplish

There is no wrong answer. This is practice, and it is also a real community.

Create the Pre-Seeded PR

Create a PR from a practice-review branch with a meaningful change to learning-room/docs/welcome.md - add one paragraph, change one heading, correct one small issue. This PR exists so participants can practice reviewing in Block 4 before the contribution sprint.

PR title: Expand the "What Is Open Source?" section Description: Use the PR template. Fill in all fields.

Day 1 - Pre-Session Checklist

Run through this 30 minutes before participants arrive:

GitHub Skills Pre-Test (Important)

Test each module at least 3 days before the workshop:

  1. Introduction to GitHub - complete Steps 1-3 in a test account
  2. Communicate Using Markdown - start and verify Mona creates the first issue
  3. Review Pull Requests - start and verify Mona creates the practice PR

Note: GitHub Skills modules occasionally have delayed Mona responses. If Mona does not respond within 2 minutes:

  1. Check that the repo was created as Public (Mona requires this on the free tier)
  2. Navigate to the Actions tab of the student's new repo - confirm a workflow run is listed
  3. If the workflow failed: click it → read the error → the most common cause is a rate limit (wait 1-2 minutes and re-trigger by creating another commit)
  4. Have backup screenshots of Mona's expected responses ready for demo purposes

Day 2 - Pre-Session Checklist

GitHub Skills - Facilitator Script

Block 1: Introducing Introduction to GitHub

"Before we explore the learning-room repo, I want you to do something first. We're going to navigate to a GitHub Skills module - this is an interactive learning course built into GitHub itself. When you activate it, GitHub creates a copy of the course repository in your own account. Then a bot called Mona starts guiding you through steps - and it responds to real GitHub actions that you take."

Walk through the setup together. Wait until everyone sees Mona's Issue #1 before continuing.

"Look at your repositories list. You now own a repository on GitHub. Mona is waiting inside it. Keep that tab open - we'll come back to it throughout the day."

Block 3: Mona Responds to the PR

When participants create their PR and Mona responds:

"Pause what you're doing. Navigate to your Pull Request tab in your Skills repo. What does Mona say? Read it with your screen reader."

Wait a moment.

"What just happened is exactly how real open source bots work. Dependabot, GitHub Actions CI, automated labelers - they all watch for GitHub events and respond automatically. You just experienced that for the first time on your own repository."

Wrap-Up: Completion Certificates

When checking Skills module completions:

"Navigate to github.com/skills/introduction-to-github. Do you see your completion badge? That's yours. It's tied to your GitHub profile. It will be there when you apply for jobs, when you introduce yourself to a new open source community, when you want to demonstrate that you know how to use GitHub."

Managing Learning Room Automation

The Learning Room includes comprehensive automation that provides instant feedback while preserving the educational value of human peer review.

Automation Components

1. PR Validation Bot (.github/workflows/learning-room-pr-bot.yml)

2. Skills Progression Engine (.github/workflows/skills-progression.yml)

3. Student Pairing & Grouping (.github/workflows/student-grouping.yml)

Before the Workshop: Configure Automation

Update Student Roster (.github/data/student-roster.json)

{
  "cohort": "Your Cohort Name 2024",
  "facilitators": ["your-github-username"],
  "students": [
    {
      "username": "student-github-username",
      "name": "Student Display Name",
      "timezone": "America/Los_Angeles",
      "interests": ["accessibility", "frontend"],
      "pronouns": "they/them",
      "screenReader": false,
      "mergedPRs": 0,
      "currentLevel": "Beginner",
      "badges": [],
      "joinedDate": "2024-01-15"
    }
  ]
}

Verify Workflows Are Enabled

Test Automation

  1. Open a test PR before workshop
  2. Verify bot comments within ~30 seconds
  3. Check that labels are applied
  4. Verify validation results are accurate
  5. Test @bot help keyword response

During the Workshop: Interacting with Automation

Introducing the Bot (Day 1, Block 5)

"When you open your PR, you'll see a comment from a bot within about 30 seconds. This bot is not grading you - it's teaching you. Read its feedback carefully. It will tell you about accessibility issues, link you to resources, and celebrate things you did well."

Walk through a sample bot comment:

"The bot is consistent and instant, but it's not perfect. If you disagree with its feedback, comment on your PR explaining why. Always request human review - peer review teaches things the bot cannot."

Monitoring Bot Behavior

Watch for:

Overriding Bot Checks

If bot incorrectly flags something:

  1. Facilitator comments: "Bot feedback incorrect here - [explanation]"
  2. Approve PR despite bot warning
  3. File issue to improve validation script later

Manual Skill Progression Adjustments

If a student completes work outside tracked PRs:

  1. Update their entry in .github/data/student-roster.json
  2. Increment mergedPRs count
  3. Update currentLevel if appropriate
  4. Add badges to badges array
  5. Commit and push to apply

Creating Study Groups

Manual Creation: Run the student-grouping workflow manually:

  1. Navigate to Actions tab
  2. Select "Student Pairing & Grouping"
  3. Click "Run workflow"
  4. Choose pairing strategy:
    • random: Shuffle and divide
    • skill_match: Mix skill levels (recommended)
    • timezone_match: Group by timezone
  5. Bot creates issue thread for each group

Group Sizes:

Monitoring Groups:

Automation Philosophy

Automation Provides:

Human Review Provides:

The Goal: Automation handles technical checks so humans can focus on higher-level feedback, mentorship, and community building.

Troubleshooting Automation

Bot not commenting:

Incorrect validation results:

Bot commenting multiple times:

Skills not unlocking:

Peer reviewers not assigned:

Customizing Automation

Adjusting Validation Rules: Edit .github/scripts/validate-pr.js:

Changing Skill Progression: Edit .github/data/challenge-progression.json:

Adding New Challenges:

  1. Create issue template in .github/ISSUE_TEMPLATE/
  2. Add to learning-room/docs/CHALLENGES.md
  3. Document in .github/docs/LEARNING_PATHS.md
  4. Add to progression data

Post-Workshop: Reviewing Automation Impact

After the workshop, analyze:

Collect Feedback: Create issue labeled automation-retrospective asking:

Iterate: Use feedback to improve validation scripts, messages, and workflows for next cohort.

Accessibility Notes for Facilitators

Personalizing This Workshop

The curriculum, agent files, and practice documents are designed to be adapted:

The workshop is licensed under Creative Commons Attribution. Attribution: "Based on the Open Source AT Hackathon Learning Room by [your name]."

Chapter-by-Chapter Facilitation Guide

Chapters 0-2: Pre-Workshop & Orientation (Day 1 Blocks 0-1)

Chapter 0: Pre-Workshop Setup

Chapter 1: Understanding GitHub's Web Structure

Chapter 2: Navigating Repositories

Chapter 3: The Learning Room (Day 1 Block 1-5)

Key before starting: Everyone must read this chapter before Day 1 begins. It explains the environment, PR workflow, bot feedback, and peer review model.

Chapters 4-6: Issues, VS Code Accessibility & Pull Requests (Day 1 Blocks 2-4)

Chapter 4: Working with Issues

Chapter 6: Working with Pull Requests

Chapter 7: Merge Conflicts (Reference; covered in-context)

When it matters: Usually NOT during the workshop, but valuable for future contribution

Chapter 8: Culture & Etiquette (Day 1 Block 6)

Purpose: Building inclusive communities, understanding norms

Chapters 9-10: Tracking & Notifications (Day 1 Block 6)

Chapter 9: Labels, Milestones, Projects

Chapter 10: Notifications

Chapters 5 and 11-16: Day 2 Deep Dives (Day 2 Blocks 1-5)

Chapter 5: VS Code Accessibility

Chapter 11: Git & Source Control

Chapter 12: GitHub Pull Requests Extension

Chapter 13: GitHub Copilot (Introduce carefully)

Chapter 14: Accessible Code Review

Chapter 15: Issue Templates (Usually pre-configured; reference only)

Chapter 16: Accessibility Agents

Accessibility Testing Checklist for Facilitators

Before Day 1 and Day 2 start, verify the following on your demo machine AND participant machines:

Screen Reader Setup (NVDA)

Screen Reader Setup (JAWS)

Screen Reader Setup (VoiceOver - macOS)

Browser Configuration

VS Code (for Day 2)

Exercise Verification

Facilitator Q&A Guide

"I pressed H and nothing happens"

Problem: Single-key navigation is disabled or broken.
Solution:

  1. Are you in Browse Mode? (NVDA: press NVDA+Space)
  2. Is the page a GitHub page, or a different website where H might be reserved?
  3. Try pressing H again while holding Shift in case it's a mode issue.
  4. Refresh the page (Ctrl+R or Cmd+R).
    Escalation: If still broken, it may be a NVDA/screen reader version issue - consider restarting the screen reader.

"I can't find the Issues tab"

Problem: Repository navigation is not visible/not announced.
Solution:

  1. Press H to go to the next heading. If you hear "Code," "Issues," "Pull Requests," you're in the repo navigation.
  2. If not, press D to jump to the Repository Navigation landmark.
  3. Once you hear any of those tabs, press K to navigate the links within it.
    Teaching point: "The tabs are links, not buttons. Press Enter, not Space."

"The table is hard to read"

Problem: Markdown tables are rendering but the screen reader isn't navigating them well.
Solution:

  1. Are you in table mode? (NVDA: when in a table, you can press NVDA+Alt+T to toggle table mode)
  2. In table mode, arrow keys navigate cells, Ctrl+Home jumps to the first cell.
  3. If still hard: read the table headers first (usually first row or first column), then navigate row by row.
    Accessibility note: Markdown tables have limitations - HTML tables are more accessible, but Markdown is what we have here.

"I filed an issue but the bot didn't respond"

Problem: Bot has not commented after 5 minutes.
Solution:

  1. Verify the repository is PUBLIC (bots require this on free tier).
  2. Navigate to the Actions tab in that repository. You should see a workflow run. Has it completed?
  3. If the run failed, click it to see logs. Most common error: GitHub Actions didn't have permission to comment (Settings → Actions → Permissions).
  4. If the run is still pending, wait up to 2 minutes more.
  5. If 5+ minutes and no action: refresh the page. Sometimes the UI doesn't update.
    Escalation: Manually verify the issue was created (it should be in the Issues tab).

"I can't commit because 'nothing to commit'"

Problem: A student tries to commit but the VS Code terminal says "nothing to commit."
Solution:

  1. Did you actually edit a file? Open the file and make sure your changes are there.
  2. Did you save the file? (Ctrl+S)
  3. Does the Source Control panel show the file as changed? (Ctrl+Shift+G)
  4. If you see the file in the Source Control panel but it won't show as changed: the file may not be part of your workspace. Make sure you're working in the right folder.
    Teaching point: Git only tracks changes to files it already knows about. If you create a new file, it will show in Source Control as "Untracked" - you must add it first (click the + next to the filename).

"I don't understand the diff"

Problem: The GitHub diff view is hard to parse on a screen reader.
Solution:

  1. If reading a diff on GitHub's web, try requesting changes (R key) to get a suggestion view (side-by-side or inline).
  2. If reading in VS Code, the diff viewer is more accessible than GitHub's web diff.
  3. Alternative: just read the file as it is now. The diff is additive context - not always necessary to review.
    Accessibility teaching point: "Code reviews aren't always about reading diffs. They're about understanding intent. Ask the author: What changed and why? That conversation might matter more than parsing the diff syntax."

"I keep getting permission denied when pushing"

Problem: Git push fails with "Permission denied" or "Authentication failed."
Solution:

  1. Are you authenticated to GitHub? (gh auth status)
  2. If not authenticated: gh auth login → follow prompts.
  3. If authenticated but still failing: Is the branch name spelled right? (git branch to see your current branch)
  4. Is the remote correct? (git remote -v to verify origin points to your fork)
  5. Have you pushed this branch before, or is it new? (First push requires git push -u origin branch-name)
    Common beginner error: Trying to push to the upstream repo instead of their fork. Push to your fork first, then open a PR upstream.

"The agent command didn't work"

Problem: User typed @accessibility-lead write a test and got no response.
Solution:

  1. Are you in Copilot Chat? (Icon in the left sidebar, or Ctrl+Alt+I)
  2. Did you include the @agent-name? Some agents are invoked with @ symbol, some with /slash commands.
  3. Did Copilot Chat load correctly? Try closing the panel and reopening.
  4. Is the agent installed in your .github/agents/ folder? (Verify by navigating to .github/ and checking the file list)
  5. If you're offline, agents won't work (they're running in the cloud).
    Escalation: Check Copilot Chat logs (bottom of chat panel) for error messages.

"I don't know what commit message to write"

Problem: Student is staring at the commit message prompt, uncertain what to say.
Talking point / suggestion: 

"A good commit message is:
- First line: one sentence, present tense, no more than 50 characters
- Example: 'Add keyboard shortcuts for JAWS'
- Second line: blank line
- Rest (optional): details explaining why (not what - git diff shows what)
- Example: 'JAWS users requested this feature in issue #42'"

Demo:

git commit -m "Add keyboard shortcuts for JAWS

This resolves #42. JAWS users noted the shortcuts were missing from the docs."

"What if I make a breaking change?"

Problem: Participant is worried their edit might break something.
Reassurance:

  1. "You're editing documentation or adding features. Documentation changes don't break anything - they clarify. Feature additions go in a PR where others review first."
  2. "If you do break something, that's how we learn. We'll see it in CI (if we have tests) or in code review. You revert it, we move on."
  3. "The main branch is protected. You can't accidentally push breaking changes directly - you must PR first, be reviewed, then merge."

"How do I know if my PR is good enough?"

Problem: Participant is uncertain whether their work meets the standard.
Process to explain:

  1. Submit your PR (you've already done the hard part).
  2. Wait for bot feedback. Does it pass checks?
  3. Request human review (ask @ people in the comments).
  4. Read their suggestions.
  5. Make changes if you agree.
  6. When you and the reviewers agree, they'll approve and merge.
  7. If you disagree with feedback, explain why in a comment. Conversation happens.
    Philosophy: "There's no 'good enough' - there's 'what did you try?' and 'what did you learn?' Your first contribution might be small, but it counts."

Common Patterns & How to Explain Them

The Fork-Edit-PR Workflow

Why it's confusing: It requires working across three repositories (upstream, your fork, local clone). Visual developers see this as click-fork-click-edit-click-PR. Screen reader users navigate three different sites.

How to teach it:

"Let me walk through the three repositories.

1. Upstream repo - Community-Access/learning-room
   This is the official repository. You can't edit it directly.

2. Your fork - [your-name]/learning-room
   When you click Fork, GitHub copies the entire repo to your account.
   This is your personal copy. You CAN edit this one.

3. Your local clone - on your laptop, in a folder
   You get the fork onto your laptop with git clone.
   You edit here, in actual files, then push back to the fork.

The flow: Edit locally → commit → push to fork → open PR from fork to upstream.
All three repositories are talking to each other, but you're the only one editing the one you control."

GitHub Actions / Automation

Why it's confusing: Something happens automatically behind the scenes. Users can't see the mechanism.

How to teach it:

"When you open a PR, GitHub has optional 'watchers' - like automated reviewers.
A bot watches for the PR and runs checks.
Did you follow the format? The bot checks.
Are there any typos? The bot can scan.
Invalid markdown? The bot flags it.
All within 30 seconds. The bot isn't smart - it's just very, very fast.
And it's not mean - it's teaching. It links you to resources, not blocking you."

Merge Conflicts

Why it's confusing: Two people can't both change the same line. Git doesn't know which version is right.

How to teach it:

"Imagine a document you and I are both editing.
You added a sentence to line 10.
I also added a sentence to line 10.
You do it first - your sentence is on main now.
I try to push my sentence to line 10.
Git says: 'I have TWO sentences here. I don't know which one is correct.'
I have to go in and pick one, delete the other, or combine them.
Then I commit the fix and push again.
It's not a failure - it's just how parallel editing works."

Questions about facilitation? Open an issue with the question label. Contributions to this guide are welcome.