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/airflow-steward.git
The following commit(s) were added to refs/heads/main by this push:
new 8ab7b39 docs(mentoring): sync family README and spec to reflect 3
shipped skills (#579)
8ab7b39 is described below
commit 8ab7b39739387665eff2efa7ac6c5bf7a2972a36
Author: Justin Mclean <[email protected]>
AuthorDate: Sat Jun 27 20:11:07 2026 +1000
docs(mentoring): sync family README and spec to reflect 3 shipped skills
(#579)
docs/mentoring/README.md said "Status: proposed. No skill ships yet."
but pr-management-mentor, good-first-issue-author, and mentoring-welcome
are all on main. Update the README to reflect the experimental state,
list all three skills with purpose and status, document the adopter
contract (mentoring-config.md, good-first-issue-config.md,
mentoring-welcome-config.md), and add standard cross-references.
Update docs/mentoring/spec.md to add mentoring-welcome to the Status
table (three skills shipped, not two).
Generated-by: Claude (Opus 4.7)
---
docs/mentoring/README.md | 103 ++++++++++++++++++++++++++++++++---------------
docs/mentoring/spec.md | 5 ++-
2 files changed, 74 insertions(+), 34 deletions(-)
diff --git a/docs/mentoring/README.md b/docs/mentoring/README.md
index 9622257..117fd45 100644
--- a/docs/mentoring/README.md
+++ b/docs/mentoring/README.md
@@ -3,8 +3,10 @@
**Table of Contents** *generated with
[DocToc](https://github.com/thlorenz/doctoc)*
- [Mentoring skill family](#mentoring-skill-family)
+ - [Skills](#skills)
+ - [What each skill covers](#what-each-skill-covers)
+ - [Adopter contract](#adopter-contract)
- [Status](#status)
- - [Adopter contract (proposed)](#adopter-contract-proposed)
- [Cross-references](#cross-references)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
@@ -14,45 +16,82 @@
# Mentoring skill family
-**Status: proposed.** No skill ships yet. The framework lands the
-spec — tone guide, hand-off protocol, adopter contract — ahead
-of any skill code so the project's tone choices are reviewable
-independently of runtime behaviour. See
-[`MISSION.md` § Mentoring](../../MISSION.md#technical-scope) for
-the *why*.
-
-Why a framework skill family? Mentoring is named in
-[`MISSION.md`](../../MISSION.md) as the highest-value mode and
-the one off-the-shelf agent tooling skips. Lifting it into the
-framework lets every adopter pick up the tone work and the
-hand-off rules without re-deriving them, and lets the
-framework's contributor-sentiment evaluation cover all adopters
-at once.
+Maintainer-facing skills that join contributor threads in a teaching
+register, author newcomer-ready issues, and orient first-time contributors.
+Three skills shipped at `experimental`; a fourth (`contributor-to-committer`)
+is in-flight.
-## Status
+MISSION names Mentoring as the highest-value project-side mode and the one
+off-the-shelf agent tooling skips. The framework lands the spec — tone guide,
+hand-off protocol, adopter contract — and the skill implementations together,
+so the project's tone choices are reviewable independently of runtime
+behaviour and can be evolved without editing the skill body.
+
+## Skills
+
+| Skill | Purpose | Status |
+|---|---|---|
+| [`pr-management-mentor`](../../skills/pr-management-mentor/SKILL.md) | Draft
a teaching-register comment on a single GitHub issue or PR thread; waits for
maintainer confirmation before posting. | experimental |
+| [`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 |
+
+All three 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.
+
+### What each skill covers
-Mentoring is **proposed**. No SKILL.md exists yet. This directory
-currently contains:
+- **`pr-management-mentor`** — the thread-level Mentoring skill. Reads an
+ issue or PR thread, decides whether a teaching-register intervention is
+ warranted (clarifying question, convention pointer, paired example from a
+ prior PR), drafts the comment, and waits for maintainer confirmation before
+ posting. Never reviews code, routes PRs, or authors fixes — those are Triage
+ and Drafting respectively.
+- **`good-first-issue-author`** — the issue on-ramp skill. Takes a maintainer-
+ supplied gap or small task, applies a suitability gate (too large, security-
+ sensitive, or requiring a design decision → decline), runs through R1–R9
+ readiness criteria, and drafts one self-contained issue a newcomer can pick
+ up without prior repo context: scope, code pointers, contributing-doc links,
+ acceptance criteria, and a rough effort estimate.
+- **`mentoring-welcome`** — the first-contact skill. Triggered immediately
+ after a first-time contributor opens an issue or PR. Drafts a lightweight
+ orientation comment (contributing-guide link, community-norm pointers,
+ expected next steps). Skips silently for repeat contributors and
+ security-sensitive threads.
-- [**`spec.md`**](spec.md) — what the future skill should do:
- scope, triggers, tone, hand-off, adopter knobs.
+## Adopter contract
-A prototype skill (`pr-management-mentor`, working name) lands
-in a follow-up PR after this spec is reviewed. The skill ships
-flagged `mode: Mentoring` + `experimental` per the
-[mode lifecycle](../modes.md#mode-lifecycle).
+The skills resolve project-specific content from these files in the adopter's
+`<project-config>/` directory:
+
+| 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) |
+|
[`mentoring-welcome-config.md`](../../projects/_template/mentoring-welcome-config.md)
| `mentoring-welcome` (welcome-comment bodies, detection rules,
contributing-guide URL) |
+
+See the spec's [Adopter contract section](spec.md#adopter-contract) for the
+required key documentation.
+
+## Status
-## Adopter contract (proposed)
+**Experimental.** Three skills shipped. No adopter has run the full
+contributor-to-committer interaction path under evaluation conditions yet;
+shape may change between framework versions.
-The future skill resolves project-specific content from the
-adopter's `<project-config>/mentoring-config.md` — see the
-template at
-[`projects/_template/mentoring-config.md`](../../projects/_template/mentoring-config.md).
+An in-flight fourth skill — `contributor-to-committer` — assembles readiness
+evidence for a contributor approaching committer nomination and surfaces the
+signals `contributor-nomination` already gathers. It is not yet on `main`.
## Cross-references
- [`MISSION.md` § Mentoring](../../MISSION.md#technical-scope) —
- mode definition, RAI empowerment framing.
+ mode definition, contributor-empowerment framing.
- [`docs/modes.md` § Mentoring](../modes.md#mentoring) —
- implementation status.
-- [`spec.md`](spec.md) — full spec.
+ current implementation status.
+- [`spec.md`](spec.md) — full Mentoring spec: tone guide, hand-off
+ protocol, adopter contract.
+- [`projects/_template/README.md`](../../projects/_template/README.md) —
+ adopter scaffold index.
+- [`docs/setup/agentic-overrides.md`](../setup/agentic-overrides.md) —
+ the override mechanism every skill in this family supports.
diff --git a/docs/mentoring/spec.md b/docs/mentoring/spec.md
index bac3bf5..0c13377 100644
--- a/docs/mentoring/spec.md
+++ b/docs/mentoring/spec.md
@@ -24,12 +24,13 @@
## Status
-Experimental. Two skills shipped:
+Experimental. Three skills shipped:
| Skill | Purpose |
|---|---|
| [`pr-management-mentor`](../../skills/pr-management-mentor/SKILL.md) | Draft
a teaching-register comment on a single GitHub issue or PR thread. |
| [`good-first-issue-author`](../../skills/good-first-issue-author/SKILL.md) |
Draft a single net-new good first issue from a maintainer-supplied candidate. |
+| [`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. |
This document is the normative Mentoring spec: tone guide, hand-off
protocol, and adopter contract. The skills implement these conventions;
@@ -210,7 +211,7 @@ fixed in the shipped implementations.
- [`MISSION.md` § Mentoring](../../MISSION.md#technical-scope) —
the mode definition + responsible-AI framing.
- [`docs/modes.md` § Mentoring](../modes.md#mentoring) —
- current implementation status (experimental, 2 skills shipped).
+ current implementation status (experimental, 3 skills shipped).
-
[`.claude/skills/pr-management-triage/comment-templates.md`](../../skills/pr-management-triage/comment-templates.md)
—
tone-footer convention; `pr-management-mentor` mirrors its
format with a `mentoring` step token.
