--- name: batch-bug-shepherd description: >- Use this skill to drive a batch of suspected bugs in microsoft/apm from raw issue list to mergeable PR queue. Fan out one triage subagent per issue (LEGIT / UNCLEAR / FIXED-AT-HEAD), cross-reference legit issues against open PRs, then branch: in-flight community PR -> shepherd via the apm-review-panel skill; no PR -> fix session with TDD and a mutation-break gate. Dispatch one completion subagent per shepherd verdict to resolve panel follow-ups, push to the contributor fork (or open a superseding PR that preserves author authorship via commit trailers), and post one ready-to-merge confirmation. Maintain a single plan.md ground-truth table as canonical session state. Activate when the maintainer asks to triage a list of issues, sweep the bug queue or backlog, shepherd all bug-flagged issues this quarter, run a weekly sweep of community-reported issues, drive in-flight community PRs to merge, or work down community bug contributions -- even if "shepherd" or "batch" is not named. --- # batch-bug-shepherd - Outer-loop bug-queue orchestrator This skill is an A10 ORCHESTRATOR-SAGA over three fan-out waves (triage, shepherd-or-fix, completion) with a persisted ground-truth table between phases. It COMPOSES the [apm-review-panel](../apm-review-panel/SKILL.md) skill -- it does NOT re-implement panel review. Per-PR shepherding is delegated; per-issue verification, PR-in-flight branching, fix dispatch, completion, and the cross-session table are owned here. The skill is ADVISORY at the panel layer and EXECUTIVE at the orchestrator layer: it WILL push commits, open PRs, post comments, close superseded PRs. Every consequential write goes through a deterministic CLI (`gh`, `git`, `uv run ruff`) wrapped in plan + execute + verify (A9 SUPERVISED EXECUTION). ## Architecture invariants - **Fan-out, not serial.** Triage, shepherd, fix, and completion all run as parallel child threads via the runtime's `task` affordance. A single-loop variant of this skill is an anti-pattern -- it collapses the context-isolation win. - **Verify before fix.** No fix subagent is dispatched until the issue is reproduced on HEAD (verdict `LEGIT`). `UNCLEAR` issues are surfaced for human triage; `FIXED-AT-HEAD` issues are recommended for close. - **PR-in-flight detection is mandatory.** Before dispatching ANY fix, the orchestrator runs `gh pr list --search ""` (and scans linked PRs on the issue) for every legit issue. Skipping this step risks duplicating community work, which is the worst failure mode this skill defends against. - **Shepherd before complete.** When a community PR exists, the apm-review-panel verdict comment IS the work definition for the completion subagent. Completion does not freelance: it reads the shepherd comment, addresses each blocking-severity finding, and stops. - **Mutation-break gate.** A regression-trap test is REAL only when deleting the production guard makes it FAIL. Tests that pass with the guard deleted are logic-replay, not regression traps. The completion subagent MUST run the mutation-break check before declaring the follow-up resolved (see `assets/completion-prompt.md`). - **Superseding-PR fallback.** When push to the contributor fork fails (no `maintainerCanModify`, branch protection, or fork deleted), open a new PR under `microsoft/apm` that PRESERVES AUTHOR AUTHORSHIP via `git commit --author=""` or cherry-pick + `Co-authored-by:` trailer. Close the original PR with a courteous handoff comment referencing the superseding PR. - **Single-writer interlock per artifact.** Each apm-review-panel run posts exactly ONE comment (the panel's own contract). Each completion subagent posts exactly ONE confirmation comment after CI is green. The orchestrator never posts to a PR directly -- it delegates to the relevant subagent. - **ASCII only.** All artifacts (table, comments, commit messages, templates) use printable ASCII. No emojis, no em dashes, no unicode box-drawing. Windows cp1252 terminals will UnicodeEncodeError on anything else. - **Lint contract is the push gate.** Before any `git push`, the completion subagent runs the canonical pair: `uv run --extra dev ruff check src/ tests/ && uv run --extra dev ruff format --check src/ tests/` and both MUST be silent. See `.github/instructions/linting.instructions.md`. - **Ground-truth table is the single source of truth.** One markdown table in the session's plan.md, rewritten on every subagent return. Schema in `assets/ground-truth-table.md`. Re-read it at the start of every wave (B4 PLAN MEMENTO + B8 ATTENTION ANCHOR). - **Cross-session message reports only on green.** A completion subagent reports back to the orchestrator (via the runtime's cross-session-message affordance, or by writing a status line to plan.md if cross-session-message is unavailable) ONLY when CI is green and all blocking follow-ups landed. Failures stay in the subagent's session until resolved or escalated to a human. ## Composition with apm-review-panel `apm-review-panel` is the shepherd primitive. This skill spawns it as the body of every shepherd subagent. The spawn prompt instructs the subagent to: 1. ACTIVATE: invoke the `apm-review-panel` skill by name (the harness resolves it from its skill registry). If the harness reports the skill is not available, abort with a clear error -- do NOT attempt a partial shepherd pass. 2. LOAD: treat the skill body as the working spec for the shepherd subagent. 3. RUN: execute the panel against the target PR per that skill's contract (8 specialist personas + CEO synthesizer, single recommendation comment). 4. RETURN: a structured verdict matching `assets/verdict-schema.json` (`ready-to-merge` | `needs-author-changes` | `reject`) plus the list of blocking-severity findings the completion subagent must address. This is the only dependency between the two skills. The orchestrator NEVER reaches into apm-review-panel internals; it consumes the comment and the verdict. ## Phases Work through the phases in order. Reload the ground-truth table at each phase boundary. Do not skip the cross-reference phase. ### Phase 0 - scope resolution Input is either (a) an explicit issue list (e.g. `#123 #456 #789`) or (b) the `sweep-all` flag, which expands to: - `gh issue list --label bug --state open --json number,title,labels,body` - plus `gh issue list --state open --search "is:open no:label"` filtered by suspicion keywords (`error`, `crash`, `broken`, `regression`, `unexpected`, `traceback`, `does not work`, `cannot`, `fails`). Initialize the ground-truth table (`assets/ground-truth-table.md`) with one row per candidate. Print a brief plan to the user: candidate count, expected wave shape, and the disciplines that will be enforced (mutation-break, ASCII, lint). Ask for confirmation only if `sweep-all` produced more than 20 candidates -- otherwise proceed. ### Phase 1 - triage fan-out (WAVE 1) Spawn one child thread per candidate using `assets/triage-prompt.md`. Each subagent: - Reproduces the bug on HEAD via the smallest possible repro. - Returns a verdict JSON matching `assets/verdict-schema.json` (`triage` verdict shape). Schema-validate every return (S4). On malformed, re-spawn that subagent ONCE with a clarifying note. On second malformed, mark the row `UNCLEAR -- subagent malformed` and continue. Update the table. Move on only when every row has a triage verdict. ### Phase 2 - PR-in-flight cross-reference For every `LEGIT` row, run `gh pr list --search "" --state open --json number,title,headRefName,author,maintainerCanModify`. Also inspect each linked PR on the issue itself. Two outcomes per row: - `pr_in_flight = false` -> route to FIX in phase 3. - `pr_in_flight = true` -> capture PR number, author, fork URL, `maintainerCanModify` flag. Route to SHEPHERD in phase 3. Update the table. This phase MUST complete before any phase-3 spawn. ### Phase 3 - shepherd-or-fix fan-out (WAVE 2) Two parallel sub-waves, both fan-out: **Sub-wave 3a -- SHEPHERD.** For each PR-in-flight row, spawn a child thread with `assets/shepherd-prompt.md` (which is a thin wrapper that loads apm-review-panel and runs the panel against the captured PR). Returns: verdict + comment URL. The panel writes ONE PR comment per its own contract; the orchestrator does not post to that PR. **Sub-wave 3b -- FIX.** For each `LEGIT && !pr_in_flight` row, spawn a child thread with `assets/fix-prompt.md`. The fix subagent: - Writes failing tests FIRST (TDD). - Implements the minimum fix. - Runs the mutation-break gate (delete the new guard, confirm tests FAIL). - Runs the lint contract. - Opens a PR under `microsoft/apm` referencing the issue. - Returns PR number. Update the table with PR numbers and shepherd verdicts. Hold until every spawn returns. ### Phase 4 - completion fan-out (WAVE 3) For each PR (both 3a-shepherded community PRs and 3b-fixed PRs that need follow-ups), spawn one completion subagent with `assets/completion-prompt.md`. Each completion subagent: 1. Reads the shepherd comment (or, for own-fix PRs, its own self-review notes from the fix subagent return). 2. Resolves each blocking-severity follow-up. Common shapes: - Extract helpers; align with canonical sibling logic. - Add regression-trap tests (mutation-break gate enforced). - Fix merge conflicts; rebase if cleaner. 3. Runs the lint contract. Both commands MUST be silent. 4. Pushes: - Tries `git push ` first when `maintainerCanModify=true`. - On rejection or when the flag is false, opens a superseding PR under `microsoft/apm` via `git checkout -b supersede/ && git cherry-pick ... && gh pr create --base main --title "..." --body "Supersedes #; preserves authorship via commit trailers."`. Each commit carries `Co-authored-by: ` trailer. - Closes the superseded PR via `gh pr close --comment "Superseded by #. Thank you for the original work; the superseding PR preserves your authorship via commit trailers and resolves the panel follow-ups so we can land this promptly."`. 5. Waits for CI on the target PR. If green AND every blocking follow-up is addressed, posts ONE confirmation comment (template in `assets/final-report-template.md` -> "PR confirmation" block) summarizing the changes and citing CI evidence. 6. Cross-session-messages the orchestrator with the PR number and `status: ready-to-merge`. On failure, stays in-session and surfaces the blocker for human review; does NOT message back as green. ### Phase 5 - final report Read the table one last time. Render `assets/final-report-template.md` to the user: per-issue verdict, PR link, ready-to-merge status, unresolved blockers (with the responsible subagent's session reference), and any rows still `UNCLEAR` for human triage. ## Bundled assets - `assets/verdict-schema.json` -- JSON schema for triage, shepherd, and completion returns. Schema-validate every subagent return (S4 SCHEMA-VALIDATE). - `assets/ground-truth-table.md` -- canonical table template. Columns: `issue | verdict | pr | pr_in_flight | author | status | notes`. Updated on every subagent return. - `assets/triage-prompt.md` -- spawn body for WAVE 1 subagents. - `assets/shepherd-prompt.md` -- spawn body for WAVE 2a subagents (loads apm-review-panel). - `assets/fix-prompt.md` -- spawn body for WAVE 2b subagents. - `assets/completion-prompt.md` -- spawn body for WAVE 3 subagents. - `assets/final-report-template.md` -- the user-facing report shape AND the PR confirmation comment shape used by completion subagents. ## Operating contract for the orchestrator thread - Before each phase: re-read `plan.md` ground-truth table. Do NOT rely on recall from earlier phases. - After each subagent return: schema-validate, then update the table, then write it back to `plan.md`. - Never post to a PR directly. Delegate every PR-side write to the subagent responsible for that PR. - Never skip the cross-reference phase. The "duplicates community work" failure mode is more expensive than every other failure mode this skill defends against, combined. - Honor the lint and encoding rules transitively: every spawn prompt reminds its subagent of both. ## Out of scope - Authoring panel personas (lives in `apm-review-panel`). - Computing coverage percentages (lives in test-coverage-expert persona, invoked via apm-review-panel). - Single-PR review without a batch (use `apm-review-panel` directly). - Auto-merge or auto-label. The orchestrator does not flip merge state; the maintainer ships.