From ae1f4a152475a285a6ef5b012b81179b7270af0e Mon Sep 17 00:00:00 2001 From: Jarek Potiuk Date: Tue, 16 Jun 2026 22:13:41 -0400 Subject: [PATCH] prepare-providers-doc skill: batch classification to cut sub-agents MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The skill classified provider changes by spawning one Explore sub-agent per PR. On a normal release wave (dozens of providers, hundreds of commits) that is hundreds of sub-agents — the main reason the run is so long and token-heavy. Replace the per-PR fan-out with a volume-aware strategy: classify inline when few commits remain (≲15), otherwise spawn one sub-agent per provider that classifies that provider's whole remaining commit list in a single pass (chunking only providers with >25 commits). Multi-provider PRs are already classified independently per provider, so the provider is the natural batch unit and the breaking-change checklist is amortized across its commits instead of paid per commit. This takes the sub-agent count from O(commits) down to roughly O(providers) — often zero for incremental updates. --- .../prepare-providers-documentation/SKILL.md | 75 ++++++++++++------- 1 file changed, 49 insertions(+), 26 deletions(-) diff --git a/.agents/skills/prepare-providers-documentation/SKILL.md b/.agents/skills/prepare-providers-documentation/SKILL.md index a02798ac4997e..688160d3a2a38 100644 --- a/.agents/skills/prepare-providers-documentation/SKILL.md +++ b/.agents/skills/prepare-providers-documentation/SKILL.md @@ -4,7 +4,8 @@ description: > Replace the manual commit-by-commit classification step in `breeze release-management prepare-provider-documentation` with AI-driven classification. For each provider with pending changes, analyze every PR - (using sub-agents per PR), pay special attention to potentially breaking + (batched into one sub-agent per provider, not one per PR), pay special + attention to potentially breaking changes by inspecting the actual diff, scope multi-provider PRs to the current provider's slice, ask the release manager when uncertain, and apply version bumps + changelog entries. Use during the regular provider @@ -190,7 +191,7 @@ each commit. Note that some old providers also have legacy paths under `provider_details.possible_old_provider_paths` semantics by checking the provider's `provider.yaml` history if needed). -### Phase 3 — Classify each PR with sub-agents +### Phase 3 — Classify the PRs (inline, or batched per-provider sub-agents) For each commit, classify it into one of: @@ -218,21 +219,39 @@ Before spawning a sub-agent, apply the same fast heuristics breeze uses Note these classifications and move on — no sub-agent needed. -#### Sub-agent per PR for the rest - -For the remaining commits, spawn sub-agents in parallel (batches of 5–10 to -avoid context pressure). Use the `Explore` agent type — they need read-only -access. Brief each sub-agent with: +#### Classify the rest — batched per provider, not one agent per PR + +Classification is the token-heavy part of this skill, so spend sub-agents +sparingly. Do **not** spawn one sub-agent per PR — that is one agent per +commit and balloons to hundreds of agents on a normal release wave. Pick the +smallest fan-out that fits the volume: + +- **Few commits remain (≲ 15 across all providers) → classify inline.** Read + each PR and its provider-scoped diff yourself, in this context. Spawn no + sub-agents at all. +- **More than that → one sub-agent per provider.** Each agent classifies that + provider's *entire* remaining commit list in a single pass. This is the + natural unit: multi-provider PRs are classified independently per provider + anyway (see Cross-Cutting Rules), and one provider-scoped agent amortizes + the breaking-change checklist across all of that provider's commits instead + of paying a fresh agent spin-up per commit. Only split a provider across + more than one agent when its remaining list is large (> ~25 commits) — chunk + it then. This keeps the sub-agent count at roughly the number of providers + with pending changes, not the number of commits. + +Use the `Explore` agent type — they need read-only access. Brief each +sub-agent with its provider and the whole batch of commits it owns: ``` -Classify a single Apache Airflow provider PR. +Classify a batch of Apache Airflow provider PRs for ONE provider. -PR: # -Commit: -Subject: Provider: (path: providers//) +Commits to classify () — one row per PR: + # + # + …(this provider's full remaining list) -Tasks: +For EACH commit above: 1. Read the PR's title, body, and labels: `gh pr view --json title,body,labels,files` 2. Read the diff for the slice of the PR that touched @@ -250,14 +269,14 @@ Tasks: changes, type-hint cleanups, no user-visible behavior - skip: only tests/examples/CI for this provider's slice - min_airflow_bump: explicitly bumps the minimum Airflow version pin -4. Output strictly: - CLASSIFICATION: - CONFIDENCE: - JUSTIFICATION: - BREAKING_RISK: (set "maybe" when the diff has any - signal from the breaking-change - checklist, even if you think the - author intended otherwise) +4. Set BREAKING_RISK to "maybe" whenever the diff has any signal from the + breaking-change checklist below, even if you think the author intended + otherwise. + +Output one row per commit and nothing else, in this exact pipe format +( rows for commits): + + # | | | | Breaking-change checklist (any of these → BREAKING_RISK >= maybe; usually breaking unless clearly behind a deprecation shim): @@ -290,7 +309,8 @@ that removes a public method is breaking. A PR titled "BREAKING: rename foo" that only renames a private symbol is not. ``` -Collect all sub-agent results into a table. +Collect every sub-agent's rows (and any you classified inline) into one +classification table for Phase 3.5. ### Phase 3.5 — Confirm with the release manager @@ -542,9 +562,12 @@ If there are zero new commits for a provider, skip it. ### Incremental Phase 3 — Classify the new commits Same logic as Phase 3 of the initial run — including the auto-classify -heuristic for docs/test-only changes and the sub-agent-per-PR pattern with -the breaking-change checklist. The output is a per-provider table mapping -each new commit hash to a classification. +heuristic for docs/test-only changes and the batched classification (inline +when few commits remain, otherwise one sub-agent per provider) with the +breaking-change checklist. Incremental runs usually have only a handful of new +commits, so prefer classifying them inline rather than spawning any sub-agent. +The output is a per-provider table mapping each new commit hash to a +classification. ### Incremental Phase 3.5 — Decide whether to escalate the version bump @@ -612,8 +635,8 @@ When a single PR touches several providers (e.g. `Add Python 3.14 Support (#63520)` touches dozens), classify it **independently per provider**. The same PR can be `feature` in one provider (a real new capability) and `misc` in another (just a constraint bump in -`pyproject.toml`). Always scope the sub-agent's diff inspection to the -current provider's path: +`pyproject.toml`). Always scope the diff inspection (whether inline or in a +per-provider sub-agent) to the current provider's path: ```bash gh pr diff -- 'providers//**'