INTERSECT-training · mrmundt · Jun 22, 2026 · Jun 22, 2026 · Jun 22, 2026 · Jun 22, 2026
diff --git a/.github/workflows/check-pr-urls.yml b/.github/workflows/check-pr-urls.yml
@@ -8,11 +8,11 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:    
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v7
 
     - id: files
 #      uses: jitterbit/get-changed-files@v1 ### Hasn't been updated to Node16
-      uses: masesgroup/retrieve-changed-files@v2
+      uses: masesgroup/retrieve-changed-files@v4
       with:
         format: 'csv'
 

diff --git a/episodes/basic-issues.md b/episodes/basic-issues.md
@@ -5,54 +5,80 @@ exercises: 10
 ---
 ::::::::::::::::::::::::::::::::::::::: objectives
 
-- Become familiar with basic actions on GitHub Issues
+- Recognize what makes an issue clear and actionable.
+- Become familiar with basic actions on GitHub Issues.
 
 ::::::::::::::::::::::::::::::::::::::::::::::::::
 
 :::::::::::::::::::::::::::::::::::::::: questions
 
+- What makes a *good* issue?
 - How do you make an issue?
 - How do you interact with an open issue?
 - How do you close an issue?
 
 ::::::::::::::::::::::::::::::::::::::::::::::::::
 
-## Open an Issue
+## What Makes a *Good* Issue?
 
-To open a new issue, navigate to the issue page. Here you will see a green
-"New issue" button in the top-right. Click this to start the creation of a new issue.
+Anyone can click "New issue" and type "it's broken." The skill worth learning is writing an
+issue a teammate can actually *act on* without a follow-up conversation. A good bug report
+usually has:
 
-![](fig/new-issue.png){alt='New issue button circled in red. Button is on the top-right on the Issues page.'}
+| Ingredient | Why it matters |
+|------------|----------------|
+| **Clear, specific title** | "Crash when sorting empty folder" beats "bug" — it's findable and scannable. |
+| **Steps to reproduce** | If we can't trigger it, we can't fix it. Number the steps. |
+| **Expected vs. actual** | What *should* have happened, and what *did*. |
+| **Environment** | OS, version, language version — the details that change behavior. |
+| **One issue = one problem** | Don't bundle five bugs in one ticket; they can't be tracked or closed independently. |
 
-This will load a new page with an empty issue.
+A good *feature request* is similar: what you want, **why** (the motivation/use case), and any
+alternatives you considered. Keep these in mind for every issue you open today.
 
-![](fig/empty-issue.png){alt='Empty issue page after clicking new issue button. All details (Title, Write, Assignees, etc.) are empty.'}
+## Open an Issue
 
-A new issue has several parts:
+Click the green **New issue** button (top-right of the Issues page) to start a new issue.
 
-- _Title_: This will display on the main "Issue" page.
-- _Write_: This is an open area for the details of the issue. GitHub support Markdown formatting.
-- _Preview_: This will preview the Markdown-rendered version of the details.
+![](fig/new-issue.png){alt='New issue button circled in red. Button is on the top-right on the Issues page.'}
 
-Once an issue is filled out, the "Submit new issue" button will highlight.
+A new issue has a few parts:
+
+- _Title_: displays on the main Issues page.
+- _Write_: the details of the issue — GitHub supports **Markdown** formatting.
+- _Preview_: shows the Markdown-rendered version before you submit.
+
+Once it's filled out, the **Submit new issue** button activates.
 
 ![](fig/submit-new-issue.png){alt='Submit new issue button is now highlighted and available to press'}
 
 :::::::::::::::::::::::::::::::::::::::  challenge
 
-## Open a New Issue
+## File Your First StarSort Bug
 
-Navigate to your practice repository's issue page.
- 
-* Open a new issue titled "[YOUR NAME]'s First Issue"
-* In the "Write" section, make a heading entitled "Description"
-* Write a short sentence telling us what you ate for breakfast this morning
-* Add a code block with "Hello, World" coded in your favorite language
-* Preview your issue to make sure it looks right
-* Submit the issue!
+You're testing StarSort and it crashes when you point it at an empty image folder. Time to file
+a proper bug report! In **your practice repository's** issue page:
+
+* Open a new issue with a clear, specific **title**
+* In the "Write" section, add a `## Steps to Reproduce` heading and number the steps.
+* Add a section for **Expected vs. Actual** behavior.
+* Include a code block showing the (made-up) error message StarSort printed.
+* **Preview** to check your Markdown, then **submit**!
 
 ::::::::::::::::::::::::::::::::::::::::::::::::::
 
+::::::::::::::::::::::::::::::::::::::::::  callout
+
+## GenAI: from messy notes to a clean report
+
+Bug reports often start as a jumble: "it broke when the folder was empty, error said
+IndexError, was on my mac." Try pasting notes like that into an LLM and asking it to format a
+bug report with steps to reproduce and expected/actual sections. Then **check it against the
+good issue table** — did it invent steps or details you didn't give it? You supply the facts; the AI
+just tidies the structure.
+
+::::::::::::::::::::::::::::::::::::::::::::::::::::::
+
 On the right-hand side, there are more options that can be modified.
 
 - _Assignee_: Here you can choose a specific person to this issue.
@@ -99,20 +125,21 @@ tag other users, link to other issues or pull requests, and more.
 
 :::::::::::::::::::::::::::::::::::::::  challenge
 
-## Tag Your Instructor
+## Loop in a Maintainer
+
+A StarSort maintainer should know about your bug. Navigate to your issue from the previous
+exercise.
 
-Navigate to your issue from the previous exercise.
-
 * Write a new comment on the issue, mentioning your instructor using
   the `@` symbol.
-* Add the comment to the issue
+* Add the comment to the issue.
 
 ::::::::::::::::::::::::::::::::::::::::::::::::::
 
 ## Close an Issue
 
-We are done with this issue. We have completed the work on it, had our
-discussion, and now we don't want it cluttering up our issue list.
+Good news — a maintainer "fixed" your StarSort bug! The work is done and the discussion is
+over, so we don't want it cluttering up the open-issues list anymore.
 
 Closing an issue is simple - just click the "Close issue" button.
 
@@ -141,9 +168,11 @@ You now know the basic actions you can take on a GitHub issue!
 
 :::::::::::::::::::::::::::::::::::::::: keypoints
 
+- A good issue has a clear title, steps to reproduce, expected vs. actual behavior, and covers one problem.
 - New issues can be opened in a repository using the 'New issue' button.
 - Text on issues use Markdown styling for formatting.
 - A user can interact with issues in multiple ways: commenting, mentioning others, linking to other issues and pull requests, and more.
+- GenAI can format messy notes into a structured report, but you must supply and verify the facts.
 
 ::::::::::::::::::::::::::::::::::::::::::::::::::
 
diff --git a/episodes/introduction.md b/episodes/introduction.md
@@ -34,52 +34,77 @@ Issue trackers can be internal (team-facing) or external (user-facing). In
 this lesson, students will learn about issue tracking through the use of GitHub
 Issues.
 
+::::::::::::::::::::::::::::::::::::::::::  callout
+
+## Your mission: welcome to the StarSort team!
+
+To make this concrete, you'll spend this lesson role-playing a new contributor to
+**StarSort** — a (fictional) open-source research tool that sorts and catalogs telescope
+images. The maintainers are friendly but swamped, and the issue tracker is how the whole team
+tracks work. Throughout the lesson you'll file bug reports, triage the backlog, and set up
+templates — just like a real contributor would.
+
+(You'll do all of this in **your own practice repository** — StarSort is just the story we'll
+use to make it fun.)
+
+::::::::::::::::::::::::::::::::::::::::::::::::::::::
+
 ## The Benefits of Issue Tracking
 
-Issue tracking has numerous benefits. Some of the main ones are:
+Why bother, instead of a pile of sticky notes and "I'll remember it" promises?
+
+| Benefit | What it gives you |
+|---------|-------------------|
+| **Visibility** | All the work to be done lives in one place every team member can see. |
+| **Collaboration** | Work can be captured, organized, discussed, and assigned in a single location. |
+| **Transparency** | If the tracker is user-facing, users can follow progress and chime in. |
+
+::::::::::::::::::::::::::::::::::::::::::  callout
+
+## Where does genAI fit?
+
+Generative AI (LLMs like ChatGPT and Claude) is surprisingly handy for issue tracking — it can
+turn messy notes into a clear bug report, suggest labels, or summarize a long discussion
+thread. We'll point out useful spots throughout the lesson. The catch, as always: the AI
+drafts, but **you** review for accuracy.
 
-- _Visibility_: Work to be done is captured in one location where all team members can access it
-- _Collaboration_: Issue trackers enable good project collaboration. Work can be captured, organized, managed, and discussed in a single location
-- _Transparency_: If the issue tracking system is user-facing, users can see the status of work completed and add more information
+::::::::::::::::::::::::::::::::::::::::::::::::::::::
 
 
 ## GitHub Issues
 
 Numerous different issue tracking systems exist - both commercial and open-source,
 integrated and stand-alone.
 
-GitHub integrates issue tracking into their version control system. Every project
-on GitHub can enable an integrated issue tracker.
+GitHub integrates issue tracking right into version control: every project on GitHub can
+enable an issue tracker, reached from the **Issues** tab in the repository's navigation bar.
 
 ![](fig/intersect-nav.png){alt='INTERSECT training repository navigation bar, showing, from left to right: Code, Issues, Pull Requests, Actions, Projects, Security, Insights'}
 
-To access a repository's issues, navigate to the repository root
-page and click on "Issues" in the navigation bar. This will take you to the
-page of all "Open" issues.
+The Issues page lists all open issues; click any one to read its details and discussion. You
+can filter the list by status (Open/Closed), author, label, and more.
 
 ![](fig/intersect-issues.png){alt='INTERSECT training repository Issues pages'}
 
-Click on an issue to open it and read its details, plus any discussion
-on that issue.
-
-![](fig/intersect-issue-13.png){alt='INTERSECT training repository issue 13, titled "add merely useful + turing way to list resources?"'}
-
-You can also change the default filter on the Issues page by status ("Open" or
-"Closed"), author, and more.
-
-![](fig/intersect-filter.png){alt='Issue top-bar filter options which include Open, Closed, Author, Label, Projects, Milestones, Assignee, and Sort'}
-
-
 :::::::::::::::::::::::::::::::::::::::  challenge
 
-## Browsing Open Issues
+## Scavenger Hunt: Browsing Open Issues
+
+A real project's tracker can be huge. Let's explore one. Navigate to
+[https://github.com/spack/spack](https://github.com/spack/spack) and find the issues page.
 
-Navigate to [https://github.com/spack/spack](https://github.com/spack/spack) and find the issues page.
-
 * How many issues are currently open?
 * How many have been closed?
 * How many labels are there?
 
+:::::::::::::::::::::: solution
+
+Open vs. closed counts are the toggles at the top of the issues list; the label count is on the
+**Labels** button (or the `/labels` page). The exact numbers change daily — that's the point:
+the tracker is dynamic and constantly updated.
+
+::::::::::::::::::::::
+
 ::::::::::::::::::::::::::::::::::::::::::::::::::
 
 

diff --git a/episodes/labels.md b/episodes/labels.md
@@ -1,17 +1,19 @@
 ---
 title: "Labelling Issues"
-teaching: 5
+teaching: 6
+exercises: 8
 ---
 
 ::::::::::::::::::::::::::::::::::::::: objectives
 
-- Learn how to use labels for GitHub issues.
+- Learn how to make, modify, apply, and filter by labels for GitHub issues.
 
 ::::::::::::::::::::::::::::::::::::::::::::::::::
 
 :::::::::::::::::::::::::::::::::::::::: questions
 
 - How do you make and assign labels to issues?
+- How do labels help you triage and prioritize work?
 
 ::::::::::::::::::::::::::::::::::::::::::::::::::
 
@@ -46,27 +48,21 @@ Engineering, however, so we will need to modify these.
 
 ## Modifying Labels
 
-Labels can be added, edited, or deleted from the labels page.
-
-![](fig/label-highlights.png){alt='On the Labels page, individual label actions (Edit, Delete) circled'}
-
-Each label has three attributes:
-
-* Label name
-* Description
-* Color (Hex code)
+Labels can be added, edited, or deleted from the **Labels** page. Each label has three
+attributes: a **name**, a **description**, and a **color** (hex code).
 
 ![](fig/label-attributes.png){alt='Label attributes - label name, description, color - and the buttons "Cancel" and "Save changes"'}
 
 :::::::::::::::::::::::::::::::::::::::  challenge
 
-## Label Maker
+## Tidy Up StarSort's Labels
+
+The StarSort maintainers want the label set to fit their small research team. In **your
+practice repository's** Labels page:
 
-Navigate to your practice repository's label page.
-
 * Add a new label for `discussion`
 * Remove the label for `good first issue`
-* Modify the color on the `wontfix` label to your favorite color
+* Change the color of the `wontfix` label to your favorite color
 
 ::::::::::::::::::::::::::::::::::::::::::::::::::
 
@@ -94,15 +90,27 @@ your preferred label(s).
 
 :::::::::::::::::::::::::::::::::::::::  challenge
 
-## Stick the Label
+## Triage Time
 
-Navigate to your practice repository's issue page.
-
-* Create a new issue entitled "[YOUR NAME]'s label issue"
-* Add the `discussion` label
+A new idea came in for StarSort: supporting a new image format. In **your practice
+repository's** issue page:
+
+* Create a new issue entitled "[YOUR NAME]: support FITS image format"
+* Add the `discussion` label so the team knows it needs further discussion
 
 ::::::::::::::::::::::::::::::::::::::::::::::::::
 
+::::::::::::::::::::::::::::::::::::::::::  callout
+
+## GenAI: Triage assistant
+
+Faced with a backlog of 50 unlabeled issues? An LLM can read an issue's text and *suggest* a
+label (bug, enhancement, question...) or even a priority. It's a great way to get a first pass —
+but a human should confirm before the labels drive real decisions, since a mislabeled issue
+hides in the wrong filter.
+
+::::::::::::::::::::::::::::::::::::::::::::::::::::::
+
 ## Filter by Labels
 
 Another feature of labels within GitHub is the ability to filter issues by
@@ -123,14 +131,21 @@ You can select multiple labels or use the hints at the bottom of the
 
 :::::::::::::::::::::::::::::::::::::::  challenge
 
-## Practice Filtering
+## Filter Like a Pro
+
+Let's go back to some real research software. Navigate to
+[https://github.com/spack/spack](https://github.com/spack/spack) and find the issues page.
+
+* Filter by the `environments` label?
+* Filter by both the `environments` and `bug` labels?
+* (CHALLENGE) Filter by `question` but *exclude* `bug`?
+
+:::::::::::::::::::::: solution
+
+The last one uses the exclusion syntax in the search bar: `is:issue is:open label:question
+-label:bug`. The `-label:` prefix is the trick most people don't know.
 
-Navigate to [https://github.com/spack/spack](https://github.com/spack/spack) and
-find the issues page.
-
-* Filter by the `architecture` label
-* Filter by both the `architecture` and `architectures` labels
-* (CHALLENGE) Filter by `question` but exclude `bug`
+::::::::::::::::::::::
 
 ::::::::::::::::::::::::::::::::::::::::::::::::::
 
@@ -140,6 +155,8 @@ GitHub Issues.
 :::::::::::::::::::::::::::::::::::::::: keypoints
 
 - Labelling issues can help with organization and filtering.
+- Curate the default label set to fit your project and team size.
+- Filtering (including exclusion, e.g. `-label:bug`) makes a big backlog manageable.
 
 ::::::::::::::::::::::::::::::::::::::::::::::::::