From 275440546a9b13e028d738d6a9836dcba2c1a384 Mon Sep 17 00:00:00 2001 From: Rich Bowen Date: Wed, 15 Jul 2026 09:06:35 -0400 Subject: [PATCH] Update family README skill counts to match repo state MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Six docs/*/README.md files had stale skill counts — new skills were added without updating the docs. Corrected: - pr-management: 5→8 (added pr-stale-sweep, pre-first-pr-check, reviewer-routing) - repo-health: 6→7 (added audit-finding-fix) - mentoring: 5→6 (added newcomer-issue-explainer, annotated cross-listed skill) - contributor-growth: 7→9 (added contributor-sentiment, onboarding-concierge) - utilities: 3→4 (added skill-reconciler) - security: 9→12 (added security-issue-import-from-scan, security-issue-import-via-forwarder) Also adds docs/TODO.md tracking remaining audit findings. --- docs/contributor-growth/README.md | 10 +++++++--- docs/mentoring/README.md | 24 ++++++++++++++---------- docs/pr-management/README.md | 16 ++++++++++++++-- docs/repo-health/README.md | 20 +++++++++++++++++++- docs/security/README.md | 8 +++++--- docs/utilities/README.md | 3 ++- 6 files changed, 61 insertions(+), 20 deletions(-) diff --git a/docs/contributor-growth/README.md b/docs/contributor-growth/README.md index 158f68936..19315389e 100644 --- a/docs/contributor-growth/README.md +++ b/docs/contributor-growth/README.md @@ -28,8 +28,8 @@ 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. Seven skills cover the staged path from first contact +thresholds, measuring contributor sentiment, assembling nomination evidence, +and walking nominators through post-vote onboarding. Nine skills cover the staged path from first contact through committer promotion. Why a framework skill family? The contributor-to-committer path is one @@ -49,6 +49,8 @@ them makes the adopter configuration and the evaluation story coherent. | **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. | +| **Sentiment analysis** | [`contributor-sentiment`](../../skills/contributor-sentiment/SKILL.md) | Analyse contributor sentiment signals (issue tone, PR abandonment, response-time frustration) to surface early-warning indicators of contributor disengagement. Read-only. | +| **Onboarding concierge** | [`onboarding-concierge`](../../skills/onboarding-concierge/SKILL.md) | Interactive first-session guide for new contributors: walks through repo setup, points to good first issues, introduces project conventions and communication channels. | | **Post-vote onboarding** | [`committer-onboarding`](../../skills/committer-onboarding/SKILL.md) | Walks the nominator through ICLA check, account provisioning, permissions grant, and the welcome announcement for committer and PMC promotions at ASF TLPs and podlings. | Every stage is read-only on governance artefacts or propose-before-post: @@ -62,12 +64,14 @@ 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-sentiment`](../../skills/contributor-sentiment/SKILL.md) | Triage | experimental | +| [`onboarding-concierge`](../../skills/onboarding-concierge/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 seven skills are `experimental`; no adopter has run the full +All nine skills are `experimental`; no adopter has run the full contributor-to-committer path under evaluation conditions yet. ## Family boundary diff --git a/docs/mentoring/README.md b/docs/mentoring/README.md index 4b8a060ec..03e393bcd 100644 --- a/docs/mentoring/README.md +++ b/docs/mentoring/README.md @@ -24,9 +24,9 @@ Maintainer-facing skills that join contributor threads in a teaching 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`. +newcomers, orient first-time contributors, explain issue context to +newcomers, and track a contributor's readiness path to committer nomination. +Six 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, @@ -41,10 +41,11 @@ behaviour and can be evolved without editing the skill body. | [`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 | -| [`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 | +| [`newcomer-issue-explainer`](../../skills/newcomer-issue-explainer/SKILL.md) | Explain a single issue's context, relevant code paths, and expected approach to a newcomer who has claimed it; teaching register, never gatekeeps. | 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 | +| [`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. (`family: contributor-growth` — cross-listed here for the mentoring path continuity.) | experimental | -All five skills are read-only on tracker state or draft-then-confirm: no +All six 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. @@ -63,10 +64,13 @@ confirmation in-session. 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. + 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. +- **`newcomer-issue-explainer`** — the issue-context skill. When a newcomer + claims a good-first-issue, explains the relevant code paths, project context, + and expected approach in a teaching register. - **`contributor-to-committer`** — the readiness-tracking skill. Takes a GitHub handle, fetches their public activity on ``, and maps it against the adopter's declared committer or PMC thresholds from @@ -101,7 +105,7 @@ required key documentation. ## Status -**Experimental.** Five skills shipped. No adopter has run the full +**Experimental.** Six 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/pr-management/README.md b/docs/pr-management/README.md index 4a4a64e5e..22fba8ab8 100644 --- a/docs/pr-management/README.md +++ b/docs/pr-management/README.md @@ -18,8 +18,8 @@ > Apache-Software-Foundation-specific assumptions baked in. Maintainer-facing PR-queue management for projects with a public -contributor PR queue. Five skills that compose into a complete -triage + review + mentoring pass: +contributor PR queue. Eight skills that compose into a complete +triage + review + mentoring + hygiene pass: 1. **Agentic Triage** — sweep open PRs, classify against the project's quality criteria, propose a disposition (draft / comment / @@ -44,6 +44,15 @@ triage + review + mentoring pass: Waits for explicit maintainer confirmation before posting; never gatekeeps. Lives in the Mentoring mode but operates on the same PR surface as skills 1–4. +6. **Stale-sweep** — identify open PRs past a configurable + inactivity threshold, classify as `NUDGE` or `CLOSE-STALE`, + post one comment per PR on maintainer confirmation. +7. **Pre-first-PR check** — pre-flight a contributor's first PR + against project conventions before it reaches a human reviewer; + surfaces formatting, test, and documentation gaps. +8. **Reviewer routing** — suggest the best-fit reviewer(s) for a + new PR based on path ownership, recent review history, and + current load. Why a framework skill family? These skills were originally maintained inside one ASF project's developer-tooling repo as @@ -64,6 +73,9 @@ wording, CI-check → doc-URL map, review-criteria source files). | [`pr-management-code-review`](../../skills/pr-management-code-review/SKILL.md) | Deep code review, one PR at a time. | | [`pr-management-quick-merge`](../../skills/pr-management-quick-merge/SKILL.md) | Express-lane screener for trivial, low-risk PRs in the `ready for maintainer review` queue; surfaces ranked candidates with diff summaries and the exact merge command. Read-only on the queue; the one optional mutation (APPROVE) requires explicit per-PR confirmation. | | [`pr-management-mentor`](../../skills/pr-management-mentor/SKILL.md) | Draft a teaching-register comment on a single GitHub issue or PR thread (clarifying questions, project-convention pointers, rationale explanations); waits for explicit maintainer confirmation before posting. `mode: Mentoring` — see also [`docs/mentoring/README.md`](../mentoring/README.md). | +| [`pr-stale-sweep`](../../skills/pr-stale-sweep/SKILL.md) | Sweep open PRs for inactivity past a configurable threshold; classify as `NUDGE` or `CLOSE-STALE` and post one comment per PR on confirmation. | +| [`pre-first-pr-check`](../../skills/pre-first-pr-check/SKILL.md) | Pre-flight a contributor's first PR against project conventions before it reaches a human reviewer. | +| [`reviewer-routing`](../../skills/reviewer-routing/SKILL.md) | Suggest the best-fit reviewer(s) for a new PR based on path ownership, recent review history, and current load. | ## Adopter contract diff --git a/docs/repo-health/README.md b/docs/repo-health/README.md index de4f05669..3dde9daf0 100644 --- a/docs/repo-health/README.md +++ b/docs/repo-health/README.md @@ -7,6 +7,7 @@ - [Repo-health audits — family overview](#repo-health-audits--family-overview) - [Current skills](#current-skills) + - [`audit-finding-fix` (experimental)](#audit-finding-fix-experimental) - [`ci-runner-audit` (experimental)](#ci-runner-audit-experimental) - [`workflow-security-audit` (experimental)](#workflow-security-audit-experimental) - [`dependency-audit` (experimental)](#dependency-audit-experimental) @@ -42,6 +43,23 @@ follow. See [`docs/modes.md` § Triage](../modes.md#triage). ## Current skills +### `audit-finding-fix` (experimental) + +Takes a single audit finding (from `ci-runner-audit`, +`workflow-security-audit`, `dependency-audit`, or +`license-compliance-audit`) and drafts a targeted fix PR: code change, +commit message, and PR description. The fix addresses exactly one finding +and includes a regression check where applicable. + +Drafts only; the human committer reviews and pushes. Never modifies files +or opens PRs without explicit maintainer confirmation. + +**Adopter contract**: reads `/repo-health-config.md` +(`audit_finding_fix.pr_template`) for the PR description template and +branch-naming convention. + +--- + ### `ci-runner-audit` (experimental) Reads every GitHub Actions workflow file across one repo, a named set, one @@ -186,7 +204,7 @@ policy: . ## Status -**Experimental.** All six skills shipped. No adopter-pilot evaluation +**Experimental.** All seven skills shipped. No adopter-pilot evaluation has run end-to-end yet; shape may change between framework versions. To provide pilot feedback, copy diff --git a/docs/security/README.md b/docs/security/README.md index 51f6c6116..acd2ae8b1 100644 --- a/docs/security/README.md +++ b/docs/security/README.md @@ -27,9 +27,9 @@ End-to-end automation for an ASF project's security-issue handling process — from inbound report on the project's `security@` mailing -list through to a published CVE record on `cve.org`. Nine skills -that compose into the canonical 16-step lifecycle, plus one -read-only supporting skill for tracker-stats dashboards. +list through to a published CVE record on `cve.org`. Eleven skills +that compose into the canonical 16-step lifecycle, plus one read-only +supporting skill for tracker-stats dashboards (twelve skills total). Why a framework skill family? The 16-step process exists across the foundation; every project's security team runs essentially @@ -48,6 +48,8 @@ and reuse the skills verbatim. | [`security-issue-import`](../../skills/security-issue-import/SKILL.md) | Import new reports from `` into ``. | | [`security-issue-import-from-pr`](../../skills/security-issue-import-from-pr/SKILL.md) | Open a tracker for a security-relevant fix opened as a public PR. | | [`security-issue-import-from-md`](../../skills/security-issue-import-from-md/SKILL.md) | Bulk-import findings from a markdown report. | +| [`security-issue-import-from-scan`](../../skills/security-issue-import-from-scan/SKILL.md) | Import findings from a security scanner output (Trivy, Grype, etc.) into ``. | +| [`security-issue-import-via-forwarder`](../../skills/security-issue-import-via-forwarder/SKILL.md) | Import reports relayed through the ASF security forwarder when no direct reporter contact exists. | | [`security-issue-triage`](../../skills/security-issue-triage/SKILL.md) | Propose an initial-triage disposition (VALID / DEFENSE-IN-DEPTH / INFO-ONLY / INVALID / PROBABLE-DUP / FIX-ALREADY-PUBLIC) for each tracker still in `Needs triage`; opens a discussion comment, never flips the label. | | [`security-issue-sync`](../../skills/security-issue-sync/SKILL.md) | Reconcile a tracker against its mail thread, fix PR, release train, and archives. | | [`security-cve-allocate`](../../skills/security-cve-allocate/SKILL.md) | Allocate a CVE for a tracker (Vulnogram URL + paste-ready JSON). | diff --git a/docs/utilities/README.md b/docs/utilities/README.md index b340c8e13..ae0b987c3 100644 --- a/docs/utilities/README.md +++ b/docs/utilities/README.md @@ -38,6 +38,7 @@ They are for skill authors and framework contributors. | [`write-skill`](../../skills/write-skill/SKILL.md) | Author a new framework skill or update an existing one: frontmatter, placeholder convention, injection defenses, Privacy-LLM gate-check, and validator sign-off. | stable | | [`optimize-skill`](../../skills/optimize-skill/SKILL.md) | Optimize an existing skill by applying restructuring patterns — split an oversized `SKILL.md` into linked sibling docs, trim frontmatter, and improve eval alignment. | stable | | [`list-skills`](../../skills/list-skills/SKILL.md) | Print a live index of every skill in this repository, grouped by family, with each skill's name and first-sentence description. | stable | +| [`skill-reconciler`](../../skills/skill-reconciler/SKILL.md) | Reconcile a skill's declared state (frontmatter, sibling docs, symlinks) against the framework's conventions and surface discrepancies with proposed fixes. | stable | --- @@ -62,7 +63,7 @@ edits skill files under your control, which you review before committing. ## Status -**Stable.** All three skills are shipped and validate under +**Stable.** All four skills are shipped and validate under `skill-and-tool-validate`. They are framework-authoring tools, so they evolve with the framework's own conventions rather than with adopter pilots.