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 95ad894 docs: Mode B (mentoring) spec — tone guide + adopter
contract, no skill code yet (#63)
95ad894 is described below
commit 95ad894adf5907c5ab7a09274c12fd88c028023b
Author: André Ahlert <[email protected]>
AuthorDate: Wed May 6 20:27:42 2026 -0300
docs: Mode B (mentoring) spec — tone guide + adopter contract, no skill
code yet (#63)
* docs(mentoring): land Mode B spec ahead of any skill code
[\`MISSION.md\` § Mode B](MISSION.md#technical-scope) names conversational
mentoring as the highest-value mode and the one off-the-shelf agent
tooling skips. Per MISSION sequencing, the spec, tone guide, and
adopter contract land ahead of any skill code so the project's tone
choices are reviewable independently from the runtime behaviour.
Adds:
- docs/mentoring/spec.md — scope (in/out), triggers (opt-in only, no
auto-fire), teaching register with do/don't examples, hand-off
protocol, adopter knobs, open questions for review.
- docs/mentoring/README.md — family overview, status (proposed),
cross-references.
- projects/_template/mentoring-config.md — adopter scaffold for the
six required keys the future skill will read.
Updates docs/modes.md Mode B section to point at the new spec docs
instead of describing them as "follow-up work".
No skill code yet. A prototype \`pr-management-mentor\` skill (working
name) lands in a follow-up PR after this spec is reviewed; it ships
flagged \`mode: B\` + \`experimental\` per the mode lifecycle.
* fix(mentoring): use real Airflow contributing-docs URLs in template
Two URLs in the mentoring-config template were 404s (made up filenames).
Replace with the real filenames from apache/airflow contributing-docs:
03_contributors_quick_start.rst and 05_pull_requests.rst. Caught by
lychee link-check on PR #63.
---
docs/mentoring/README.md | 58 +++++++++
docs/mentoring/spec.md | 218 +++++++++++++++++++++++++++++++++
docs/modes.md | 18 ++-
projects/_template/mentoring-config.md | 66 ++++++++++
4 files changed, 356 insertions(+), 4 deletions(-)
diff --git a/docs/mentoring/README.md b/docs/mentoring/README.md
new file mode 100644
index 0000000..7a55e18
--- /dev/null
+++ b/docs/mentoring/README.md
@@ -0,0 +1,58 @@
+<!-- START doctoc generated TOC please keep comment here to allow auto update
-->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with
[DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Mentoring skill family](#mentoring-skill-family)
+ - [Status](#status)
+ - [Adopter contract (proposed)](#adopter-contract-proposed)
+ - [Cross-references](#cross-references)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+# 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` § Mode B](../../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.
+
+## Status
+
+Mode B is **proposed**. No SKILL.md exists yet. This directory
+currently contains:
+
+- [**`spec.md`**](spec.md) — what the future skill should do:
+ scope, triggers, tone, hand-off, adopter knobs.
+
+A prototype skill (`pr-management-mentor`, working name) lands
+in a follow-up PR after this spec is reviewed. The skill ships
+flagged `mode: B` + `experimental` per the
+[mode lifecycle](../modes.md#mode-lifecycle).
+
+## Adopter contract (proposed)
+
+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).
+
+## Cross-references
+
+- [`MISSION.md` § Mode B](../../MISSION.md#technical-scope) —
+ mode definition, RAI empowerment framing.
+- [`docs/modes.md` § Mode B](../modes.md#mode-b--conversational-mentoring) —
+ implementation status.
+- [`spec.md`](spec.md) — full spec.
diff --git a/docs/mentoring/spec.md b/docs/mentoring/spec.md
new file mode 100644
index 0000000..f970b48
--- /dev/null
+++ b/docs/mentoring/spec.md
@@ -0,0 +1,218 @@
+<!-- START doctoc generated TOC please keep comment here to allow auto update
-->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with
[DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Mode B — conversational mentoring
(spec)](#mode-b--conversational-mentoring-spec)
+ - [Status](#status)
+ - [Scope](#scope)
+ - [Triggers](#triggers)
+ - [Teaching register — tone guide](#teaching-register--tone-guide)
+ - [Voice](#voice)
+ - [Forbidden](#forbidden)
+ - [AI-attribution footer](#ai-attribution-footer)
+ - [Hand-off protocol](#hand-off-protocol)
+ - [Adopter contract](#adopter-contract)
+ - [Open questions](#open-questions)
+ - [Cross-references](#cross-references)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+# Mode B — conversational mentoring (spec)
+
+## Status
+
+Proposed. No skill code yet. This document defines what Mode B
+should do once it exists; it lands ahead of any skill so the
+project's tone choices and hand-off rules are reviewable
+independently from runtime behaviour. See
+[`MISSION.md` § Mode B](../../MISSION.md#technical-scope) and
+[`docs/modes.md` § Mode B](../modes.md#mode-b--conversational-mentoring)
+for sequencing.
+
+## Scope
+
+Mode B joins issue and PR threads in a teaching register. The
+agent's job is to lower the barrier to a contributor's *next
+useful action*. Concretely, in scope:
+
+- **Clarifying questions** when the contributor's first message
+ is ambiguous (missing repro, missing version, missing intent),
+ so a human reviewer's first read is a productive one.
+- **Pointers to project conventions** with a direct link, when
+ the contributor is missing a piece of repo context they could
+ have found themselves but did not.
+- **Explanation of *why*** a request was made, when the
+ contributor pushes back on a maintainer's review comment ("why
+ does this need a test?", "why split the PR?").
+- **Paired examples from prior PRs** when a similar pattern has
+ shipped before and a one-line link saves the contributor
+ several hours.
+- **Hand-off** to a human when the question exceeds what an
+ agent should answer (architectural taste, security-sensitive
+ design, deprecation timing, anything embargoed).
+
+Out of scope:
+
+- *Reviewing code*. That is Mode A's
+
[`pr-management-code-review`](../../.claude/skills/pr-management-code-review/SKILL.md)
+ skill. Mode B does not approve, request changes, or post inline
+ diff comments.
+- *Triage routing*. That is Mode A's
+ [`pr-management-triage`](../../.claude/skills/pr-management-triage/SKILL.md)
+ skill. Mode B does not assign labels, mark draft, or close PRs.
+- *Authoring fixes*. That is Mode C. Mode B does not open PRs or
+ edit code.
+- *Speaking for the maintainer team* on disputed decisions. Mode
+ B says "a maintainer will weigh in" and stops.
+
+## Triggers
+
+Mode B never posts unprompted on a thread it has not been
+invoked on. The skill is opt-in per invocation. Three trigger
+paths:
+
+1. **Maintainer-on-demand**. A maintainer runs
+ `/pr-management-mentor <pr-number>` (working name). The skill
+ reads the thread, decides whether a mentoring intervention is
+ warranted, drafts the comment, and waits for the maintainer
+ to confirm before posting.
+2. **First-contact filter**. After
+ [`pr-management-triage`](../../.claude/skills/pr-management-triage/SKILL.md)
+ classifies a PR as "first contributor, missing repro" (or
+ equivalent triage flag), the maintainer can chain
+ `/pr-management-mentor` on that PR. The two skills compose;
+ Mode B does not run inside Mode A by default.
+3. **Issue-thread invocation**. Same opt-in, on issues rather
+ than PRs, for the "missing version / missing repro" case.
+
+Why no auto-fire: posting a teaching-register comment without
+explicit human authorization risks the agent talking past a
+maintainer who is mid-conversation with the contributor, or
+posting on a thread where the maintainer has *deliberately* not
+replied yet. Auto-fire is a Mode-D-shaped problem and inherits
+Mode D's sequencing constraint.
+
+## Teaching register — tone guide
+
+The contributor is the audience, not the maintainer. The
+agent's voice is **patient, specific, and short**. It is not
+formal. It does not lecture. It does not perform empathy. The
+reader should leave the comment knowing what to do next, not
+feeling managed.
+
+### Voice
+
+- **First line states the action**, not the meta. "Could you add
+ the version you're running? Find it via …" not "I noticed
+ your issue and would love to help by asking a clarifying
+ question."
+- **Link, don't quote**. Pointers to docs go as a single inline
+ link with a short label. Do not paste the docs back at the
+ contributor.
+- **One ask per comment**. If the contributor is missing three
+ things, ask for them as a numbered list, not three sequential
+ paragraphs.
+- **No hedging**. "This is a known pattern, see PR #1234" not
+ "It seems like this might possibly be similar to PR #1234,
+ although I'm not certain". The hedge tax falls on the
+ contributor, who then has to decide how seriously to take the
+ pointer.
+
+### Forbidden
+
+- Praise without specificity. "Great question!" and "Thanks for
+ the contribution!" are noise. They train the contributor to
+ skim.
+- Restating the contributor's message back to them. "So what
+ you're saying is …" — the contributor knows what they said.
+- AI self-reference outside the attribution footer. The footer
+ says it once; the body should not.
+- Speaking for the maintainer. "The maintainers will probably
+ want X" — Mode B does not predict maintainer decisions. It
+ says "a maintainer will reply on this; in the meantime,
+ here's the convention" and stops.
+
+### AI-attribution footer
+
+Every contributor-facing comment ends with the same footer
+convention used by
+[`pr-management-triage/comment-templates.md`](../../.claude/skills/pr-management-triage/comment-templates.md),
+adjusted to name the mentoring step rather than the triage
+step. The expansion lives in the adopter's
+`<project-config>/mentoring-config.md → ai_attribution_footer`.
+
+The footer is non-negotiable: it calibrates the contributor's
+trust (AI-drafted, may be wrong) and points at the project's
+documented two-stage process.
+
+## Hand-off protocol
+
+The agent bows out and pings a human when:
+
+1. The contributor pushes back on a substantive design point.
+ Mode B answers "why is this convention" once. If the
+ contributor disagrees, Mode B does not argue; it pings the
+ maintainer.
+2. The question touches security, embargoed work, deprecation
+ timing, or anything not covered by public documentation.
+ Mode B does not improvise on these surfaces.
+3. The thread reaches `<max_agent_turns>` (configurable, default
+ 2). After that the agent stops engaging on the thread
+ regardless of content.
+4. The contributor explicitly asks for a human ("can a
+ maintainer look at this?").
+
+The hand-off is one comment: a `@`-mention of the configured
+maintainer team, a one-line summary of the open question, and
+the agent's silence afterwards. The agent does not summarise
+the conversation; the maintainer reads the thread.
+
+## Adopter contract
+
+Per-project values live in `<project-config>/mentoring-config.md`.
+See the template at
+[`projects/_template/mentoring-config.md`](../../projects/_template/mentoring-config.md).
+Required keys:
+
+| Key | Purpose |
+|---|---|
+| `mentoring_invocation_command` | Slash-command name (e.g.
`/pr-management-mentor`). |
+| `maintainer_team_handle` | `@<org>/<team>` mentioned on hand-off. |
+| `ai_attribution_footer` | Literal footer markdown. Mirrors the triage-footer
convention. |
+| `convention_pointers` | Table of `{trigger phrase} → {docs link, one-line
label}` so the agent links rather than paraphrases. |
+| `max_agent_turns` | Integer, default 2. Hard ceiling on consecutive agent
comments per thread. |
+| `out_of_scope_topics` | Explicit list of topics on which the agent always
hands off (security, deprecation, license, etc.). |
+
+## Open questions
+
+Surfaced here so reviewers can weigh in before the skill is
+built.
+
+- **Should Mode B post on the project's mailing list, or only
+ on GitHub threads?** Current draft: GitHub only. Mailing-list
+ mentoring lives in the human maintainer's voice; the agent
+ does not have a list-subscriber identity.
+- **Is the AI-attribution footer the same wording as the triage
+ footer, or distinct?** Current draft: same wording, different
+ step token. One contributor-trust calibration is easier to
+ reason about than two.
+- **Should the maintainer review every Mode B draft, or can
+ they pre-authorize a class of comments (e.g., "always ok to
+ ask for repro")?** Current draft: every draft is reviewed.
+ Pre-authorization is Mode-D-shaped and inherits the same
+ sequencing constraint.
+
+## Cross-references
+
+- [`MISSION.md` § Mode B](../../MISSION.md#technical-scope) —
+ the mode definition + responsible-AI framing.
+- [`docs/modes.md` § Mode B](../modes.md#mode-b--conversational-mentoring) —
+ current implementation status (proposed).
+-
[`.claude/skills/pr-management-triage/comment-templates.md`](../../.claude/skills/pr-management-triage/comment-templates.md)
—
+ closest existing surface; informs the tone-footer convention
+ but is not Mode B.
+- [`AGENTS.md`](../../AGENTS.md) — repository-level rules every
+ mode inherits.
diff --git a/docs/modes.md b/docs/modes.md
index e8abc01..404c6df 100644
--- a/docs/modes.md
+++ b/docs/modes.md
@@ -93,10 +93,20 @@ Two notes on the boundaries:
[`MISSION.md` § Mode B](../MISSION.md#technical-scope) names this
the highest-value mode and the one off-the-shelf agent tooling
-skips. Implementation is tracked as future work; spec, tone
-guide, and adopter configuration template land in a follow-up
-PR before any skill code, so the project's tone choices are
-reviewable independently from the runtime behaviour.
+skips. Per MISSION sequencing, the spec — tone guide, hand-off
+protocol, adopter contract — lands ahead of any skill code so
+the project's tone choices are reviewable independently from
+the runtime behaviour.
+
+| Doc | Purpose |
+|---|---|
+| [`docs/mentoring/README.md`](mentoring/README.md) | Family overview, current
status, planned shape. |
+| [`docs/mentoring/spec.md`](mentoring/spec.md) | What the future skill should
do: scope, triggers, register, hand-off, adopter knobs. |
+|
[`projects/_template/mentoring-config.md`](../projects/_template/mentoring-config.md)
| Adopter-config scaffold the future skill will read. |
+
+A prototype skill (`pr-management-mentor`, working name) lands
+in a follow-up PR after the spec is reviewed; it ships flagged
+`mode: B` + `experimental`.
The closest existing surface is
[`pr-management-triage/comment-templates.md`](../.claude/skills/pr-management-triage/comment-templates.md),
diff --git a/projects/_template/mentoring-config.md
b/projects/_template/mentoring-config.md
new file mode 100644
index 0000000..91ac478
--- /dev/null
+++ b/projects/_template/mentoring-config.md
@@ -0,0 +1,66 @@
+<!-- START doctoc generated TOC please keep comment here to allow auto update
-->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents** *generated with
[DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Apache Airflow — mentoring (Mode B)
configuration](#apache-airflow--mentoring-mode-b-configuration)
+ - [Identifiers](#identifiers)
+ - [Convention pointers](#convention-pointers)
+ - [Out-of-scope topics](#out-of-scope-topics)
+ - [AI-attribution footer](#ai-attribution-footer)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+<!-- SPDX-License-Identifier: Apache-2.0
+ https://www.apache.org/licenses/LICENSE-2.0 -->
+
+# Apache Airflow — mentoring (Mode B) configuration
+
+**This file is a placeholder ahead of the Mode B skill landing.**
+The skill does not exist yet (Mode B is proposed per
+[`docs/modes.md`](../../docs/modes.md#mode-b--conversational-mentoring)).
+The keys below match the
+[Mode B spec](../../docs/mentoring/spec.md#adopter-contract)
+and are the values the future skill will read. New adopters
+should copy this file into their own
+`<project-config>/mentoring-config.md` and replace every
+Airflow-specific value with their project's equivalents.
+
+## Identifiers
+
+| Key | Value |
+|---|---|
+| `mentoring_invocation_command` | `/pr-management-mentor` |
+| `maintainer_team_handle` | `@apache/airflow-committers` |
+| `max_agent_turns` | `2` |
+
+## Convention pointers
+
+Triggers that the future skill will detect, mapped to the docs
+link the comment should reference instead of paraphrasing.
+
+| Trigger | Link | One-line label |
+|---|---|---|
+| Missing version on bug report |
https://airflow.apache.org/docs/apache-airflow/stable/start.html | "How to find
your Airflow version" |
+| Missing repro |
https://github.com/apache/airflow/blob/main/contributing-docs/03_contributors_quick_start.rst
| "Contributors quick start" |
+| First-time contributor PR setup |
https://github.com/apache/airflow/blob/main/contributing-docs/05_pull_requests.rst
| "How to open a PR" |
+
+## Out-of-scope topics
+
+The skill always hands off to a human when the thread touches:
+
+- Security-sensitive design (CVE-adjacent, embargoed work)
+- Deprecation timing (which release will drop X)
+- License questions (compatibility, header policy)
+- Provider-specific architectural taste
+
+## AI-attribution footer
+
+```markdown
+---
+
+_Note: This comment was drafted by an AI-assisted mentoring tool and may
contain mistakes. Once you have addressed the points above, an Apache Airflow
maintainer — a real person — will take the next look. We use this [two-stage
process](https://github.com/apache/airflow/blob/main/PROCESS.md) so that our
maintainers' limited time is spent where it matters most: the conversation with
you._
+```
+
+Replace the two-stage-process URL with the project's documented
+mentoring/triage policy. Replace `Apache Airflow` with the
+project name.
