You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@magpie.apache.org by po...@apache.org on 2026/06/30 22:54:04 UTC
(magpie) branch main updated: docs(mentoring): sync good-first-issue-sweep into family docs and modes index (#643)
This is an automated email from the ASF dual-hosted git repository.
potiuk pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/magpie.git
The following commit(s) were added to refs/heads/main by this push:
new 974cc3e3 docs(mentoring): sync good-first-issue-sweep into family docs and modes index (#643)
974cc3e3 is described below
commit 974cc3e3164026f0c64245778c0196e4d017be1b
Author: Justin Mclean <ju...@classsoftware.com>
AuthorDate: Wed Jul 1 08:53:59 2026 +1000
docs(mentoring): sync good-first-issue-sweep into family docs and modes index (#643)
`good-first-issue-sweep` landed on main via #632 but was missing from
every shipped-state surface. Add it to the Mentoring skill table in
`docs/modes.md` (count 4→5), the Mentoring family README (count 4→5,
new description, shared config note), and the contributor-growth family
README (new Backlog curation stage row, skills table, count 6→7, adopter
contract note, and updated cross-references).
Spec changes (flip good-first-issue-sweep.md from proposed→experimental,
update overview.md) are on the control branch; noted here for the
plan/update beat to reconcile.
Generated-by: Claude (Opus 4.7)
---
docs/contributor-growth/README.md | 25 ++++++++++++++-----------
docs/mentoring/README.md | 23 +++++++++++++++++------
docs/modes.md | 5 +++--
3 files changed, 34 insertions(+), 19 deletions(-)
diff --git a/docs/contributor-growth/README.md b/docs/contributor-growth/README.md
index 91a7b255..43f60cd7 100644
--- a/docs/contributor-growth/README.md
+++ b/docs/contributor-growth/README.md
@@ -26,7 +26,7 @@ Maintainer-facing skills that span the contributor-to-committer path:
welcoming first-time contributors, keeping the issue backlog newcomer-
ready, tracking contribution activity, checking readiness against declared
thresholds, assembling nomination evidence, and walking nominators through
-post-vote onboarding. Six skills cover the staged path from first contact
+post-vote onboarding. Seven skills cover the staged path from first contact
through committer promotion.
Why a framework skill family? The contributor-to-committer path is one
@@ -42,6 +42,7 @@ them makes the adopter configuration and the evaluation story coherent.
|---|---|---|
| **First contact** | [`mentoring-welcome`](../../skills/mentoring-welcome/SKILL.md) | Drafts an orientation comment for a first-time contributor on a newly opened issue or PR; detects first-time authorship via the GitHub `author_association` field and skips repeat contributors. |
| **Issue on-ramp** | [`good-first-issue-author`](../../skills/good-first-issue-author/SKILL.md) | Drafts one net-new good first issue from a supplied gap or small task; a suitability gate and R1–R9 readiness checklist gate the draft; waits for maintainer confirmation before filing via `gh`. |
+| **Backlog curation** | [`good-first-issue-sweep`](../../skills/good-first-issue-sweep/SKILL.md) | Sweeps the open issue backlog for existing issues that could be labelled as good first issues; scores each against the G1–G7 suitability rubric; classifies as READY / NEAR-MISS / SKIP and proposes labels after explicit maintainer confirmation. |
| **Activity tracking** | [`contributor-activity-sweep`](../../skills/contributor-activity-sweep/SKILL.md) | Produces a read-only GitHub activity card (PRs authored, code reviews, issues, comments) over a configurable window. |
| **Readiness check** | [`contributor-to-committer`](../../skills/contributor-to-committer/SKILL.md) | Maps a contributor's GitHub activity against the adopter's PMC-declared committer or PMC thresholds; surfaces a traffic-light brief (Not yet / Approaching / Ready to nominate) and a gap table showing what would close each remaining gap. Read-only; never opens a nomination thread. |
| **Nomination brief** | [`contributor-nomination`](../../skills/contributor-nomination/SKILL.md) | Assembles evidence prose for a committer or PMC vote thread: activity breadth, consistency, vendor-neutrality context, and a nomination-ready summary. Read-only; never posts to any list. |
@@ -57,12 +58,13 @@ without explicit maintainer confirmation.
|---|---|---|
| [`mentoring-welcome`](../../skills/mentoring-welcome/SKILL.md) | Mentoring | experimental |
| [`good-first-issue-author`](../../skills/good-first-issue-author/SKILL.md) | Mentoring | experimental |
+| [`good-first-issue-sweep`](../../skills/good-first-issue-sweep/SKILL.md) | Mentoring | experimental |
| [`contributor-activity-sweep`](../../skills/contributor-activity-sweep/SKILL.md) | Triage | experimental |
| [`contributor-to-committer`](../../skills/contributor-to-committer/SKILL.md) | Mentoring | experimental |
| [`contributor-nomination`](../../skills/contributor-nomination/SKILL.md) | Triage | experimental |
| [`committer-onboarding`](../../skills/committer-onboarding/SKILL.md) | Triage | experimental |
-All six skills are `experimental`; no adopter has run the full
+All seven skills are `experimental`; no adopter has run the full
contributor-to-committer path under evaluation conditions yet.
## Family boundary
@@ -70,10 +72,11 @@ contributor-to-committer path under evaluation conditions yet.
This family sits **alongside** two overlapping skill families:
- [`docs/mentoring/README.md`](../mentoring/README.md) — the Agentic Mentoring
- mode spec and family overview. `mentoring-welcome` and
- `good-first-issue-author` carry `mode: Mentoring` and are also
- listed in that spec. The families cross-reference each other; a later
- maturity review may clarify the boundary or merge the two into one.
+ mode spec and family overview. `mentoring-welcome`,
+ `good-first-issue-author`, and `good-first-issue-sweep` carry
+ `mode: Mentoring` and are also listed in that spec. The families
+ cross-reference each other; a later maturity review may clarify the
+ boundary or merge the two into one.
- [`docs/issue-management/README.md`](../issue-management/README.md) —
general-issue triage and fix workflow. The contributor-growth family
reads GitHub activity data about contributors, not issue content; the
@@ -99,11 +102,11 @@ adopter's `<project-config>/` directory:
| [`contributor-nomination-config.md`](../../projects/_template/contributor-nomination-config.md) | `contributor-nomination` (activity-window length, committer / PMC thresholds, required-areas gates); also used by `contributor-to-committer` as a fallback when `committer-readiness.md` is absent |
| [`committer-readiness.md`](../../projects/_template/committer-readiness.md) | `contributor-to-committer` (per-target threshold tables for committer/PMC readiness, assessment window; takes precedence over `contributor-nomination-config.md`) |
| [`mentoring-welcome-config.md`](../../projects/_template/mentoring-welcome-config.md) | `mentoring-welcome` (tone knobs, contributing-doc links, AI-attribution footer wording) |
-| [`good-first-issue-config.md`](../../projects/_template/good-first-issue-config.md) | `good-first-issue-author` (issue-tracker URL, getting-started link, out-of-scope topic list) |
+| [`good-first-issue-config.md`](../../projects/_template/good-first-issue-config.md) | `good-first-issue-author`, `good-first-issue-sweep` (issue-tracker URL, getting-started link, GFI-label name, suitability rubric threshold) |
## Status
-**Experimental.** All six skills are on main with eval suites; no
+**Experimental.** All seven skills are on main with eval suites; no
adopter has run the full contributor-to-committer path end-to-end under
evaluation conditions.
@@ -124,10 +127,10 @@ per-project policy knobs before a skill can safely propose anything):
- [`docs/modes.md` § Triage](../modes.md#triage) — mode taxonomy the
three Agentic Triage-mode family skills declare against.
- [`docs/modes.md` § Mentoring](../modes.md#mentoring) — mode taxonomy
- the two Agentic Mentoring-mode family skills declare against.
+ the three Agentic Mentoring-mode family skills declare against.
- [`docs/mentoring/README.md`](../mentoring/README.md) — the Agentic Mentoring
- mode family overview, which cross-references `mentoring-welcome` and
- `good-first-issue-author`.
+ mode family overview, which cross-references `mentoring-welcome`,
+ `good-first-issue-author`, and `good-first-issue-sweep`.
- [`projects/_template/README.md`](../../projects/_template/README.md) —
adopter scaffold index, including the three contributor-growth config
templates listed in the Adopter contract above.
diff --git a/docs/mentoring/README.md b/docs/mentoring/README.md
index 1b635174..b71ae69e 100644
--- a/docs/mentoring/README.md
+++ b/docs/mentoring/README.md
@@ -20,9 +20,10 @@
> Apache-Software-Foundation-specific assumptions baked in.
Maintainer-facing skills that join contributor threads in a teaching
-register, author newcomer-ready issues, orient first-time contributors, and
-track a contributor's readiness path to committer nomination.
-Four skills shipped at `experimental`.
+register, author newcomer-ready issues, curate the existing backlog for
+newcomers, orient first-time contributors, and track a contributor's
+readiness path to committer nomination.
+Five skills shipped at `experimental`.
MISSION names Agentic Mentoring as the highest-value project-side mode and the one
off-the-shelf agent tooling skips. The framework lands the spec — tone guide,
@@ -38,8 +39,9 @@ behaviour and can be evolved without editing the skill body.
| [`good-first-issue-author`](../../skills/good-first-issue-author/SKILL.md) | Draft one net-new good first issue from a supplied gap or small task; a suitability gate and R1–R9 readiness checklist gate the draft; waits for maintainer confirmation before filing via `gh`. | experimental |
| [`mentoring-welcome`](../../skills/mentoring-welcome/SKILL.md) | Draft a first-contact orientation comment for a first-time contributor on a newly opened issue or PR; detects first-time authorship via the GitHub `author_association` field; skips repeat contributors. | experimental |
| [`contributor-to-committer`](../../skills/contributor-to-committer/SKILL.md) | Read-only readiness tracker that maps a contributor's GitHub activity against the adopter's declared committer/PMC thresholds; surfaces a traffic-light brief (Not yet / Approaching / Ready to nominate) plus the specific evidence gaps that remain. | experimental |
+| [`good-first-issue-sweep`](../../skills/good-first-issue-sweep/SKILL.md) | Sweep the open issue backlog for existing issues that could be labelled as good first issues; scores each against the G1–G7 suitability rubric and classifies as READY / NEAR-MISS / SKIP; proposes labels only after explicit maintainer confirmation. | experimental |
-All four skills are read-only on tracker state or draft-then-confirm: no
+All five skills are read-only on tracker state or draft-then-confirm: no
skill posts, labels, closes, or files anything without explicit maintainer
confirmation in-session.
@@ -69,6 +71,15 @@ confirmation in-session.
Approaching / Ready to nominate) plus a gap table showing exactly what
evidence the contributor still needs. Read-only; never opens a nomination
thread, sends a message, or modifies any record.
+- **`good-first-issue-sweep`** — the backlog-curation skill. Sweeps the
+ open issue backlog and scores each issue against the G1–G7 suitability
+ rubric (scope, self-containment, code pointer, small effort, no security
+ sensitivity, no architectural decision, no deprecation decision).
+ Classifies each as READY (propose the GFI label), NEAR-MISS (surface
+ specific edits that would make it GFI-ready), or SKIP (not suitable).
+ Complements `good-first-issue-author`: the sweep stocks the on-ramp queue
+ from existing work; the author creates net-new issues from supplied gaps.
+ Read-only; proposes labels only after explicit maintainer confirmation.
## Adopter contract
@@ -78,7 +89,7 @@ The skills resolve project-specific content from these files in the adopter's
| File | Used by |
|---|---|
| [`mentoring-config.md`](../../projects/_template/mentoring-config.md) | `pr-management-mentor` (tone knobs, hand-off team, footer, `max_agent_turns`) |
-| [`good-first-issue-config.md`](../../projects/_template/good-first-issue-config.md) | `good-first-issue-author` (candidate-scope rules, R1–R9 threshold, filing target) |
+| [`good-first-issue-config.md`](../../projects/_template/good-first-issue-config.md) | `good-first-issue-author`, `good-first-issue-sweep` (candidate-scope rules, GFI-label name, suitability rubric threshold) |
| [`mentoring-welcome-config.md`](../../projects/_template/mentoring-welcome-config.md) | `mentoring-welcome` (welcome-comment bodies, detection rules, contributing-guide URL) |
| [`committer-readiness.md`](../../projects/_template/committer-readiness.md) | `contributor-to-committer` (committer/PMC threshold declarations: PR count, review count, issue participation, tenure window) |
@@ -87,7 +98,7 @@ required key documentation.
## Status
-**Experimental.** Four skills shipped. No adopter has run the full
+**Experimental.** Five skills shipped. No adopter has run the full
contributor-to-committer interaction path under evaluation conditions yet;
shape may change between framework versions.
diff --git a/docs/modes.md b/docs/modes.md
index f46aada5..65a056d0 100644
--- a/docs/modes.md
+++ b/docs/modes.md
@@ -57,7 +57,7 @@ Autonomous* (the renamed former *Auto-merge*).
| Mode | Purpose | Status | Skill count |
|---|---|---|---|
| **Triage** | *(Agentic Triage)* Issues, security reports, PRs: spot, classify, route, surface duplicates. Every output is a suggestion the human signs off on. | stable (security) / experimental (pr-management, issue-management, contributor-nomination, repo-health, release-management) | 30 |
-| **Mentoring** | *(Agentic Mentoring)* Joins issue and PR threads in a teaching register: clarifying questions, pointers to project conventions, paired examples from prior PRs, hand-off to a human when scope exceeds the agent. Also authors net-new good first issues to lower onboarding latency. | experimental | 4 |
+| **Mentoring** | *(Agentic Mentoring)* Joins issue and PR threads in a teaching register: clarifying questions, pointers to project conventions, paired examples from prior PRs, hand-off to a human when scope exceeds the agent. Also authors net-new good first issues and curates the existing backlog to lower onboarding latency. | experimental | 5 |
| **Drafting** | *(Agentic Drafting)* Agent drafts a fix for a well-scoped problem and opens a PR; every PR is reviewed and merged by a human committer. | stable (security-only); experimental (issue-management, audit-findings, release-management family) | 9 |
| **Pairing** | *(Agentic Pairing)* Developer-side dev-cycle skills with mentorship intrinsic — multi-agent review pipelines, self-review and pre-flight patterns, scoped fix drafting under the developer's driver's seat. | experimental | 2 |
| **Agentic Autonomous** | Auto-merge restricted to objectively boring change classes only (lint, dependency bumps inside an allow-list, license-header insertion, formatting, broken-link repair). | off | 0 |
@@ -126,7 +126,7 @@ Three notes on the boundaries:
## Mentoring
-**Status: experimental. 4 skills shipped.**
+**Status: experimental. 5 skills shipped.**
[`MISSION.md` § Agentic Mentoring](../MISSION.md#technical-scope) names this
the highest-value project-side mode and the one off-the-shelf agent
@@ -140,6 +140,7 @@ choices were reviewable independently from the runtime behaviour.
| [`good-first-issue-author`](../skills/good-first-issue-author/SKILL.md) | Draft one net-new good first issue from a supplied gap or small task (suitability gate + readiness checklist); waits for maintainer confirmation before filing. | experimental |
| [`mentoring-welcome`](../skills/mentoring-welcome/SKILL.md) | Draft a first-contact orientation comment for a first-time contributor on a newly opened issue or PR; detects first-time authorship via `author_association`, drafts a welcome with contributing-guide link and expected next steps; waits for maintainer confirmation before posting. | experimental |
| [`contributor-to-committer`](../skills/contributor-to-committer/SKILL.md) | Read-only readiness tracker mapping a contributor's GitHub activity against the adopter's PMC-declared committer/PMC thresholds; surfaces a traffic-light brief (Not yet / Approaching / Ready to nominate) plus the specific evidence gaps that remain. | experimental |
+| [`good-first-issue-sweep`](../skills/good-first-issue-sweep/SKILL.md) | Sweep the open issue backlog for existing issues that could be labelled as good first issues; scores each against the G1–G7 suitability rubric and classifies as READY / NEAR-MISS / SKIP; proposes labels only after explicit maintainer confirmation. | experimental |
| Doc | Purpose |
|---|---|