Skip to content

docs(mentoring): sync good-first-issue-sweep into family docs and modes index #643

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
justinmclean wants to merge 1 commit into
base: main
Choose a base branch
from
+34 −19
Open

docs(mentoring): sync good-first-issue-sweep into family docs and modes index #643

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 14 additions & 11 deletions docs/contributor-growth/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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. |
Expand All @@ -57,23 +58,25 @@ 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

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
Expand All @@ -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.

Expand All @@ -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.
Expand Down
23 changes: 17 additions & 6 deletions docs/mentoring/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand All @@ -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.

Expand Down Expand Up @@ -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

Expand All @@ -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) |

Expand All @@ -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.

Expand Down
5 changes: 3 additions & 2 deletions docs/modes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down Expand Up @@ -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
Expand All @@ -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 |
|---|---|
Expand Down