docs: upgrade all chapter challenges to gold standard with GitHub Skills refs

Author: GitHub Workshop Bot

.github/docs/LEARNING_PATHS.md

@@ -31,12 +31,12 @@ Chapter 4 is the first **issue-based challenge chapter** with short, confidence-
 ### Chapter 4 Challenge Set
 
 1. **Create your first issue** - file a new issue with a clear title and description.
-2. **Claim a challenge issue** - comment on an existing beginner issue to claim it.
-3. **Ask one clarifying question** - add a question comment on your claimed issue.
+2. **Comment and @mention** - leave a comment on a classmate's issue and tag them with an @mention.
+3. **Add a sub-issue** - break a larger issue into smaller, trackable pieces.
 
 > **Branch guidance for Chapter 4:** Chapter 4 focuses on issue skills. You do NOT need to create a branch or edit any files for these challenges. All your work happens in GitHub issue threads. File editing and branches start in Chapter 5.
 >
-> **How completion works:** When you finish all three challenges, post a comment on your assigned Chapter 4 challenge issue with links to the issues you created, claimed, and commented on. The facilitator reviews your issue activity directly. No pull request is required for Chapter 4.
+> **How completion works:** When you finish all three challenges, post a comment on your assigned Chapter 4 challenge issue with links to the issues you created, commented on, and organized. The facilitator reviews your issue activity directly. No pull request is required for Chapter 4.
 
 ### Challenge 4.1 Step-by-Step: Create Your First Issue
 
@@ -61,46 +61,45 @@ Chapter 4 is the first **issue-based challenge chapter** with short, confidence-
 
 **You are done when:** Your new issue appears in the Issues list with your username as the author, a clear title, and a detailed description.
 
-### Challenge 4.2 Step-by-Step: Claim a Challenge Issue
+### Challenge 4.2 Step-by-Step: Comment and @Mention
 
-**Goal:** Find an existing beginner challenge issue and claim it by leaving a comment.
+**Goal:** Leave a comment on another student's issue and use an @mention to notify them.
 
 **Where you are working:** the Issues tab of the `learning-room` repository on GitHub.com.
 
-1. Open the Issues tab in the `learning-room` repository.
-2. Use the search filter to find beginner issues. Type in the filter bar:
-   ```text
-   is:open label:"challenge: beginner"
-   ```
-3. Browse the results and pick one issue that interests you.
-4. Open the issue by activating its title link.
-5. Read the issue description to understand what needs to be done.
-6. Scroll to the comment box at the bottom of the issue.
-7. Type: `I'd like to try this!`
-8. Activate the **Comment** button (or press `Ctrl+Enter`).
-9. Note the issue number (for example, `#42`). This is the issue you will fix in Chapter 5.
-
-**You are done when:** Your comment appears in the issue thread, and other participants can see you have claimed the work.
-
-### Challenge 4.3 Step-by-Step: Ask One Clarifying Question
-
-**Goal:** Practice asking a useful question before starting implementation work.
-
-**Where you are working:** the issue you claimed in Challenge 4.2.
-
-1. Open the issue you claimed in Challenge 4.2.
-2. Re-read the issue description carefully. Think about:
-   - Is anything unclear about what needs to change?
-   - Do you know which file to edit?
-   - Do you understand the expected result?
-3. Scroll to the comment box.
-4. Write one specific question. Examples:
-   - "Should I add the paragraph after the existing heading or create a new subsection?"
-   - "The issue mentions a broken link. Is the correct URL documented somewhere else in the repo?"
-   - "Should the shortcut table keep the same column order, or can I reorganize it?"
-5. Activate the **Comment** button.
-
-**You are done when:** Your question comment appears in the issue thread. A facilitator or peer will respond.
+1. Open the **Issues** tab in the `learning-room` repository.
+2. Find an issue created by a classmate (look for issues from Challenge 4.1, or browse recent open issues).
+3. Open the issue by activating its title link.
+4. Read the issue description to understand what they reported.
+5. Scroll to the comment box at the bottom of the issue.
+6. Write a helpful comment that **@mentions the issue author by username**. Examples:
+   - "@classmate I can confirm this - the link in setup-guide.md goes to a 404 page."
+   - "@classmate Good catch! I think the correct shortcut is Insert+F7, not Insert+F5."
+   - "@classmate I'd suggest adding the paragraph right after the 'Who Can Contribute' heading."
+7. Activate the **Comment** button (or press `Ctrl+Enter`).
+
+**Why @mentions matter:** When you type `@username`, GitHub sends that person a notification. This is how real open source teams communicate - you signal who needs to see your message. It also bridges into Chapter 9 (Notifications) where you will configure how you receive these alerts.
+
+**You are done when:** Your comment appears in the thread and includes an @mention (the username renders as a clickable link).
+
+### Challenge 4.3 Step-by-Step: Add a Sub-Issue
+
+**Goal:** Break a larger issue into smaller, trackable pieces using GitHub's sub-issue feature.
+
+**Where you are working:** the issue you created in Challenge 4.1 (or any open issue you have permission to edit).
+
+> **What are sub-issues?** Sub-issues let you decompose a big task into smaller steps, each tracked independently. The parent issue shows a progress bar as sub-issues are completed. This is how teams organize real work - a single "Fix accessibility in welcome.md" issue might have sub-issues for each specific fix.
+
+1. Open the issue you created in Challenge 4.1.
+2. Look for the **Sub-issues** section in the issue sidebar (right side on desktop). If you do not see it, look for an **Add sub-issue** button or the **Create sub-issue** option below the issue description.
+3. Activate **Add sub-issue** and choose **Create new sub-issue**.
+4. Give the sub-issue a clear title that describes one specific piece of the parent issue. For example, if the parent is "Fix accessibility in welcome.md":
+   - Sub-issue: "Add alt text to welcome banner image"
+   - Sub-issue: "Fix heading hierarchy in Getting Started section"
+5. Add a short description and activate **Create**.
+6. The sub-issue now appears nested under the parent issue with a progress indicator.
+
+**You are done when:** Your parent issue shows at least one sub-issue in the Sub-issues section.
 
 ### Completing Chapter 4: Submit Your Evidence
 
@@ -109,35 +108,36 @@ When you have finished all three challenges, go to your **assigned Chapter 4 cha
 ```text
 Chapter 4 completed:
 - Challenge 4.1: Created issue #[number]
-- Challenge 4.2: Claimed issue #[number] (commented)
-- Challenge 4.3: Asked question on issue #[number]
+- Challenge 4.2: Commented with @mention on issue #[number]
+- Challenge 4.3: Added sub-issue to issue #[number]
 ```
 
-Replace `[number]` with the actual issue numbers. The facilitator will review your issue activity and mark the challenge complete.
+Replace `[number]` with the actual issue numbers. Then close your Chapter 4 challenge issues. The facilitator will review your issue activity.
 
 ### Expected Outcomes
 
 - Student can create an issue with a clear title and description.
-- Student can claim a challenge issue in a public thread.
-- Student can ask a useful question before starting implementation.
+- Student can communicate in issue threads using @mentions.
+- Student can organize work by breaking issues into sub-issues.
 
 ### If You Get Stuck
 
-1. Re-open `learning-room/docs/CHALLENGES.md` and pick one beginner issue.
-2. Use the issue search filter: `is:open label:"challenge: beginner"`.
-3. If claim/comment fails, refresh and retry once.
-4. Ask facilitator for a direct issue link and continue.
+1. Can't find a classmate's issue? Filter the Issues tab by `is:open` and look for recent ones.
+2. @mention not working? Make sure you type `@` immediately followed by the username with no space.
+3. Sub-issue option not visible? Ask a facilitator - the feature may need to be enabled for the repository.
+4. Still stuck? Ask a facilitator for a direct issue link.
 
 ### Learning Moment
 
-Issues are not just task lists. They are collaborative spaces where clear communication reduces confusion and prevents rework.
+Issues are collaborative spaces, not just task lists. An @mention tells someone "I need your attention here." Sub-issues turn vague tasks into clear checklists. Both skills are used daily in real open source projects.
 
 ### Learning Pattern Used in This Chapter
 
 1. Start with a small, safe action (create an issue).
-2. Practice communication in public issue threads (claim and question).
-3. Leave clear evidence in the issue timeline.
-4. Build momentum for file editing and PR work in Chapter 5.
+2. Practice communication in public issue threads (@mention a peer).
+3. Organize work into smaller pieces (sub-issues).
+4. Leave clear evidence in the issue timeline.
+5. Build momentum for file editing and PR work in Chapter 5.
 
 
 ## Local Git Alternative: Working from Your Clone

docs/04-working-with-issues.md

@@ -30,7 +30,7 @@ Chapter 5 is the first **PR-validated chapter** where students convert issue wor
 
 ### Chapter 5 Challenge Set
 
-1. **Create one small branch change** - edit the file specified in your claimed issue.
+1. **Create one small branch change** - edit a practice file on a new branch.
 2. **Open a linked PR** - use the PR template and include `Closes #XX`.
 3. **Pass required checks** - respond to bot feedback until all required checks pass.
 
@@ -43,11 +43,13 @@ Chapter 5 is the first **PR-validated chapter** where students convert issue wor
 
 ### Challenge 5.1 Step-by-Step: Create One Small Branch Change
 
-**Goal:** Edit the file referenced in the issue you claimed in Chapter 4 (Challenge 4.2).
+**Goal:** Edit one of the practice files and save your change on a new branch.
 
 **Where you are working:** the `learning-room` repository on GitHub.com, using the web editor.
 
-**Before you start:** Open the issue you claimed in Chapter 4.2 and note which file needs editing. The issue description tells you the file path and what to fix. The practice files are:
+**Before you start:** Open your **assigned Chapter 5.1 challenge issue** (the one titled "Chapter 5.1: Create One Small Branch Change (@yourname)"). The issue description tells you which file to edit and what to fix.
+
+The Learning Room has three practice files with intentional problems. Your assigned issue points you to one of them:
 
 The following table summarizes the practice files in the learning-room, what each file contains, and the type of issues to look for.
 
@@ -90,8 +92,7 @@ The following table summarizes the practice files in the learning-room, what eac
    - "Correct NVDA modifier key in keyboard-shortcuts.md"
 2. In the **Body** field, use the PR template if one is provided. Make sure to include:
    - A summary of what you changed and why (at least 50 characters).
-   - The line `Closes #XX` where `XX` is the number of your **assigned Chapter 5 challenge issue** (not the issue you claimed in Chapter 4, unless they are the same).
-   - If you are also closing the issue you claimed in Chapter 4, add that reference too: `Also addresses #YY`.
+   - The line `Closes #XX` where `XX` is the number of your **assigned Chapter 5 challenge issue**.
 3. Verify the **base branch** is `main` and the **compare branch** is your `fix/yourname-issueXX` branch.
 4. Activate the **Create pull request** button.
 
@@ -194,7 +195,7 @@ The GitHub CLI walks you through title, body, base branch, and reviewers.
 
 **What happens next is identical:** the Learning Room bot validates your PR, posts feedback, and you request a human reviewer - the same as the web workflow.
 
-> **Tip:** You can also use your `username-practice` branch instead of creating a feature branch. Switch to it with `git checkout username-practice` (replacing `username` with your GitHub username, all lowercase).
+> **Tip:** You can also create a named feature branch with `git checkout -b fix/yourname-issueXX` if you prefer that naming convention over the practice branch.
 
 </details>
 

docs/05-working-with-pull-requests.md

@@ -14,39 +14,81 @@ Chapter 6 uses **one controlled practice challenge** so students can learn confl
 - **Challenge count:** 1
 - **Time:** under 10 minutes
 - **Evidence:** issue-linked PR and completion comment
-- **Pattern:** observe -> resolve -> verify
+- **Pattern:** observe, resolve, verify
 
-### Chapter 6 Challenge: Resolve Conflict Markers
+### Chapter 6 Challenge Set
+
+1. **Resolve conflict markers** - identify and clean up conflict markers in a practice file, then open a linked PR.
+
+> **Branch guidance for Chapter 6:** Use a short-lived feature branch: `fix/yourname-issueXX` (for example, `fix/maria-issue48`). The same pattern you used in Chapter 5.
+
+### Challenge 6.1 Step-by-Step: Resolve Conflict Markers
+
+**Goal:** Identify the three types of conflict markers in a practice file, decide which content to keep, remove the markers, and submit a clean PR.
+
+**Where you are working:** the `learning-room` repository on GitHub.com (web editor) or in VS Code if you cloned locally.
+
+**Before you start:** Open your **assigned Chapter 6 challenge issue** (the one titled "Chapter 6.1: Resolve Conflict Markers (@yourname)"). The issue description tells you which practice file contains the conflict markers.
 
 Practice sample: [`learning-room/docs/samples/chapter-6-conflict-practice-sample.md`](../learning-room/docs/samples/chapter-6-conflict-practice-sample.md)
 
-1. Open the assigned merge-conflict practice issue.
-2. Edit only the designated practice file/section.
-3. Remove conflict markers (`<<<<<<<`, `=======`, `>>>>>>>`) and keep the intended final content.
-4. Open PR with `Closes #XX` and complete with a short issue comment summary.
+1. Open the practice file specified in your challenge issue.
+2. Search the file for `<<<<<<<`. This is the **start marker** - it shows where the conflict begins.
+3. Read the content between `<<<<<<<` and `=======`. This is **your version** (the current branch).
+4. Read the content between `=======` and `>>>>>>>`. This is **their version** (the incoming branch).
+5. Decide which content to keep:
+   - Keep only your version, or
+   - Keep only their version, or
+   - Combine both versions into one clean paragraph.
+6. Delete all three marker lines:
+   - The `<<<<<<< HEAD` line (or similar)
+   - The `=======` separator line
+   - The `>>>>>>> branch-name` line
+7. Review the file to confirm no marker lines remain. Search for `<<<<<<<` again - there should be zero results.
+8. Commit your changes on a branch named `fix/yourname-issueXX`.
+9. Open a pull request with:
+   - Title: `fix: resolve conflict markers in [filename]`
+   - Body: Include `Closes #XX` (your challenge issue number) and a 1-2 sentence description of which content you kept and why.
+
+**Screen reader tip:** Use your screen reader's find command (`Ctrl+F` in browser, `Ctrl+H` in VS Code) to jump directly to `<<<<<<<`. The markers are plain text, so they are fully readable.
+
+**You are done when:** Your PR passes bot validation checks and contains no remaining conflict markers.
+
+### Completing Chapter 6: Submit Your Evidence
+
+When your PR is open and passing checks, post a comment on your assigned Chapter 6 challenge issue:
+
+```text
+Chapter 6 completed:
+- Challenge 6.1: Opened PR #[number] resolving conflict markers in [filename]
+- Content decision: kept [your version / their version / combined both] because [reason]
+```
 
 ### Expected Outcomes
 
-- Student can identify conflict markers immediately.
-- Student can remove markers and keep intended content.
-- Student can submit a clean, issue-linked PR after resolution.
+- Student can identify the three conflict marker lines (`<<<<<<<`, `=======`, `>>>>>>>`) immediately.
+- Student can read both sides of a conflict and make an intentional content decision.
+- Student can remove all markers and submit a clean, issue-linked PR.
 
 ### If You Get Stuck
 
-1. Pause and read marker blocks line by line before editing.
-2. Keep one side, or combine both sides when both lines are valid.
-3. Delete all marker lines (`<<<<<<<`, `=======`, `>>>>>>>`).
-4. Ask facilitator to sanity-check final content before opening PR.
+1. Can't find the markers? Use `Ctrl+F` and search for `<<<<<<<` - they are always in sets of three.
+2. Not sure which side to keep? Read both versions aloud. Pick the one that is clearer, or combine them.
+3. Accidentally deleted too much? Undo with `Ctrl+Z` and start the section over.
+4. PR bot says content is wrong? Double-check that zero marker lines remain - search for `<<<<<<<`, `=======`, and `>>>>>>>`.
+5. Ask facilitator to sanity-check your final content before opening the PR.
 
 ### Learning Moment
 
-Merge conflicts are not failures. They are a normal collaboration checkpoint and a chance to make an intentional content decision.
+Merge conflicts are not failures. They are a normal collaboration checkpoint and a chance to make an intentional content decision. In real open source projects, conflicts happen whenever two people edit near the same lines. The skill is not avoiding them - it is resolving them calmly and clearly.
 
-### Why this chapter is structured this way
+### Learning Pattern Used in This Chapter
 
-- Real conflicts can be unpredictable for new contributors.
-- Controlled practice keeps the experience safe and repeatable.
-- Students still get real issue and PR workflow practice.
+1. Start with a controlled, safe conflict (practice file with known markers).
+2. Learn to read the conflict structure (your version vs. their version).
+3. Make a deliberate content decision (not just deleting randomly).
+4. Submit clean evidence through the PR workflow.
+5. Build confidence for real conflicts in future contributions.
 
 
 ## Local Git Alternative: Resolving Conflicts from Your Terminal