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 `/` 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 | |---|---|