batch-bug-shepherd

batch-bug-shepherd - Outer-loop bug-queue orchestrator

This skill is an A10 ORCHESTRATOR-SAGA over fan-out waves (triage, strategic-alignment, PR-cross-reference, fix, drive-to-merge, conflict-resolution) with a persisted ground-truth table between phases. It COMPOSES the shepherd-driver skill as the per-PR drive-to-merge engine -- it does NOT re-implement the review + fold + push + CI loop. shepherd-driver transitively COMPOSES apm-review-panel; this skill inherits that edge and never reaches into panel internals directly. It also COMPOSES the apm-ceo persona (host-repo agent at .apm/agents/apm-ceo.agent.md) for the strategic-alignment gate, which checks every LEGIT bug against PRINCIPLES.md before allowing fix / drive work to proceed. Per-PR shepherding is delegated to shepherd-driver; per-issue verification, strategic alignment, PR-in-flight branching, greenfield fix dispatch, post-wave mergeability re-probe, 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

These 18 rules bind every wave. The one-line essence is below; the FULL binding text (rationale, edge cases, inherited-from-driver detail) lives in references/invariants.md. Load references/invariants.md before planning Phase 0 -- the summaries here are dispatch anchors, not the complete contract.

• Fan-out, not serial. Triage / alignment / fix / drive run as parallel child threads; single-loop is an anti-pattern.
• Verify before fix. No fix dispatched until the bug reproduces on HEAD (LEGIT); UNCLEAR -> human, FIXED-AT-HEAD -> close.
• PR-in-flight detection is mandatory. gh pr list every legit issue before any fix; duplicating community work is the worst failure mode this skill defends against.
• Drive, do not split shepherd from complete. ONE shepherd-driver subagent owns the whole per-PR loop; no separate panel + completion waves.
• Mutation-break gate. A regression trap is real only if deleting the production guard makes the test FAIL.
• Canonical-owner gate (driver-enforced). Every fix gets one architecture classification vs .github/instructions/architecture.instructions.md; a new owner, centralization, or split-authority repair needs the full dual guardrail (behavioral + static + test_architecture_* + mutation break) before ready-to-merge. shepherd-driver enforces and returns it; the orchestrator only records the evidence.
• Superseding-PR fallback (inherited). On contributor-fork push failure the driver opens an authorship-preserving PR under microsoft/apm and returns superseded.
• Single-writer interlock. One idempotent panel comment + one driver advisory per PR; the orchestrator never posts to a PR.
• ASCII only. Printable ASCII in every artifact (cp1252 safety).
• Lint contract is the push gate (inherited). ruff check + ruff format --check silent before any git push.
• Ground-truth table is the single source of truth. One plan.md table, rewritten on every return, re-read at each wave start (B4 PLAN MEMENTO + B8 ATTENTION ANCHOR).
• Cross-session message reports only on green. Failures stay in the subagent session until resolved or escalated to a human.
• Operator visibility is a contract. Progress mermaid + live table at every boundary; dispatch table before every fan-out (assets/progress-diagram.md).
• Mergeability is post-wave truth. Re-probe mergeStateStatus before claiming ready; Phase 5 resolves conflicts with --force-with-lease (bare --force prohibited).
• Two-comment-per-PR cap. Driver advisory + resolution confirmation only; the in-loop panel comment is idempotent and does not add to the count. No third comment, ever.
• Bias toward folding (inherited). The driver folds in-scope follow-ups into the PR; only genuinely separable work becomes a tracking issue.
• Strategic-alignment gate before drive. Phase 1.5 runs one apm-ceo subagent per LEGIT row; demoted rows skip Phase 2-5; the gate fails open to aligned, aborts only if the persona / PRINCIPLES.md is missing.
• Worktree isolation. Every fix and drive child runs in its OWN git worktree (one per issue/PR); never fan out mutating children against a shared REPO_ROOT (they would race on .git/index and the checked-out branch). Triage is read-only and may share one.

Composition with shepherd-driver

shepherd-driver is the per-PR drive-to-merge engine. This skill spawns ONE shepherd-driver subagent per PR (both in-flight community PRs and own greenfield fix PRs) using the spawn body ../shepherd-driver/assets/shepherd-driver-prompt.md. The driver owns the whole convergence loop -- Copilot classification, apm-review-panel, fold-vs-defer, push, CI watch, with its own caps -- and returns a completion_return matching ../shepherd-driver/assets/completion-schema.json (ready-to-merge | advisory-with-deferred | superseded | blocked). Terminal returns also pass the deterministic semantic gate in ../shepherd-driver/scripts/owner_touch_gate.py.

The cross-PR conflict-resolution / mergeability phase is ALSO shepherd-driver's: Phase 5 delegates to ../shepherd-driver/assets/conflict-resolution-prompt.md with the step-by-step gate in ../shepherd-driver/references/mergeability-gate.md.

shepherd-driver is a same-repo LOCAL SIBLING declared in apm.yml (dependencies.apm: [../shepherd-driver]). PROBE for it before the drive wave -- a tool call, not an assertion from recall (A9 SUPERVISED EXECUTION):

test -f ../shepherd-driver/assets/shepherd-driver-prompt.md \
  && test -f ../shepherd-driver/assets/completion-schema.json \
  && test -f ../shepherd-driver/scripts/owner_touch_gate.py \
  && echo "shepherd-driver present" \
  || echo "MISSING shepherd-driver - stop and ask the operator"

On a probe MISS, STOP and ask the operator to restore the sibling; do NOT re-implement the loop inline (avoids HAND-ROLLED HALLUCINATION and PHANTOM DEPENDENCY). The driver transitively composes apm-review-panel and probes for it at its own preflight, returning status: blocked on a miss. The orchestrator uses only shepherd-driver's declared prompt, schema, and owner-gate interfaces; it NEVER re-implements shepherd-driver or apm-review-panel internals.

Phases

Work through the phases in order. Reload the ground-truth table at each phase boundary. Do not skip the cross-reference phase.

At every phase boundary (and once at the run start, once at the end), render the progress mermaid diagram + the live ground-truth table to chat per assets/progress-diagram.md. Before every fan-out wave, also render the dispatch table mapping subagent_id to target. These are not optional -- they are the operator's only real-time window into a multi-wave parallel saga.

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.

Then render the progress mermaid diagram for the first time per assets/progress-diagram.md -- every phase pending, with the candidate count N substituted into the P0 and P1 labels. Print the live (empty) ground-truth table below it. This is the operator's anchor frame for the run.

Phase 1 - triage fan-out (WAVE 1)

Re-render the progress diagram with P1 styled active. Print the dispatch table mapping each triage-<issue> subagent_id to its target issue BEFORE issuing the parallel spawns.

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 1.5 - strategic-alignment gate (WAVE 1.5)

Re-render with P15 active (substitute L LEGIT count). If L = 0, render P1.5 as skipped and pass through.

Load references/strategic-alignment-gate.md when entering this phase -- it holds the binding procedure (external-dep probes, fail-open semantics, deferred-PR strategic-rejection subagent).

Probe .apm/agents/apm-ceo.agent.md and PRINCIPLES.md. Either missing -> ABORT. Print the dispatch table for the ceo-align-<issue> subagents, then spawn L parallel threads with assets/strategic-alignment-prompt.md. Returns are strategic_alignment_return JSON (verdict in aligned | aligned-with-reservations | out-of-scope | wrong-direction). Schema-validate per retry-once; on second malformed, route as aligned with gate_note (fail-open).

Update strategic_verdict + strategic_rationale columns. Demoted rows flip to status triaged-deferred and are SKIPPED by Phase 2/3/4/5. aligned-with-reservations rows stay in saga; downstream phases MUST surface the reservations.

Phase 2 - PR-in-flight cross-reference

Re-render the progress diagram with P1 done and P2 active. Substitute L (LEGIT row count) into the P2 label.

Skip every row with status triaged-deferred (Phase 1.5 demoted). Run a LIGHTWEIGHT gh pr list probe against demoted rows only to feed the deferred-PR strategic-rejection comment procedure in references/strategic-alignment-gate.md; this read-only probe does not route demoted rows back into Phase 2.

For every LEGIT row (status triaged), run gh pr list --search "<issue-ref-or-keywords>" --state open --json number,title,headRefName,headRepository,headRepositoryOwner,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 (greenfield).
• pr_in_flight = true -> capture and store, for the Phase 4 driver spawn, every input shepherd-driver requires: PR_NUMBER (number), AUTHOR (author.login), HEAD_REPO (headRepositoryOwner.login + "/" + headRepository.name), HEAD_BRANCH (headRefName), MAINTAINER_CAN_MODIFY (maintainerCanModify), and ORIGIN = community. Route to DRIVE in Phase 4.

Store these driver-input fields in the row (table columns head_repo, head_branch, maintainer_can_modify). They are the crash-survivable evidence the Phase 4 spawn reads -- never re-derived from recall. Update the table. This phase MUST complete before any Phase 3 or Phase 4 spawn.

Phase 3 - greenfield fix fan-out (WAVE 2)

Re-render the progress diagram with P0..P2 done and P3 active. Substitute m (greenfield count) into the P3 label. If m = 0, render P3 as skipped (dashed border) and pass straight to Phase 4.

This wave is FIX-ONLY. In-flight community PRs do NOT pass through here -- they go directly to the Phase 4 drive wave. Filter out any row with status triaged-deferred (strategically demoted by Phase 1.5).

Print the fix-<issue> dispatch table (subagent_id -> issue number) BEFORE spawning. For each LEGIT && !pr_in_flight row, provision one git worktree (git worktree add <path> origin/main), record its slug in the row's worktree column, and spawn a child thread with assets/fix-prompt.md passing that worktree path as REPO_ROOT (per the Worktree-isolation invariant). 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 {kind, issue, pr, branch}.

On each return, store the Phase 4 driver inputs for the new PR: PR_NUMBER (pr), AUTHOR = the maintainer's own gh handle (these are own PRs), HEAD_REPO = microsoft/apm (same-repo head), HEAD_BRANCH (branch), MAINTAINER_CAN_MODIFY = true, and ORIGIN = own-fix. Write head_repo, head_branch, maintainer_can_modify into the row. Hold until every spawn returns.

Phase 4 - drive-to-merge fan-out (WAVE 3)

PROBE for shepherd-driver (see "Composition with shepherd-driver"). On a probe MISS, STOP and ask the operator; do NOT inline the loop.

Re-render with P4 active. Let D be the count of PRs to drive -- EVERY PR in the table that is not triaged-deferred: the in-flight community PRs (ORIGIN = community, from Phase 2) PLUS the own fix PRs (ORIGIN = own-fix, from Phase 3). Substitute D into the P4 label; if D = 0, render P4 as skipped.

Print the drive-<pr> dispatch table (subagent_id -> PR number), then spawn ONE shepherd-driver subagent per PR using ../shepherd-driver/assets/shepherd-driver-prompt.md. Each driver runs in its OWN worktree (Worktree-isolation invariant): own-fix rows REUSE the worktree their Phase 3 fix child recorded; community rows get a fresh git worktree add + gh pr checkout, recorded in worktree. Pass the inputs the prompt declares, reading each from the row (never recall); REPO_ROOT is the row's worktree path. For rows with strategic_verdict = aligned-with-reservations, ALSO pass PANEL_PRIOR = {"reservations": [<the strategic reservations as {summary} objects>]} so the driver surfaces them in the panel run and the PR advisory comment.

If D is large, batch the spawns (e.g. groups of 3) to bound nested-panel fan-out rather than launching all drivers at once.

Each driver owns the full convergence loop end-to-end and returns a completion_return matching ../shepherd-driver/assets/completion-schema.json (status enum per the Composition section). Schema-validate every return (retry-once; on second malformed, mark the row blocked and continue).

For a terminal ready-to-merge or advisory-with-deferred return, persist the returned JSON in the session state, derive BASE_SHA with git -C <row-worktree> merge-base <returned-head-sha> origin/main, then independently run:

uv run python <row-worktree>/.agents/skills/shepherd-driver/scripts/owner_touch_gate.py verify \
  --repo-root <row-worktree> --base $BASE_SHA \
  --head <returned-head-sha> --completion <session-return-json>

Do not update the table or labels until schema AND semantic verification pass. A non-zero verifier result gets the same retry-once treatment as malformed schema; on a second failure mark the row blocked with the diagnostic. This parent re-probe prevents a child from bypassing deterministic owner detection or presenting stale functional evidence.

After both gates pass, write head_sha, mergeable, merge_state_status, and ci_status from the return into the table, and remove the status/shepherding label from the driven issue (assignment stays). The orchestrator owns only validation, table update, and label cleanup -- it does NOT post to any PR.

Phase 5 - mergeability gate (WAVE 4)

Re-render with WAVE4 active. Substitute R (ready-PR count) and C (CONFLICTING-PR count) into the P5a / P5b labels. If R = 0, skip Phase 5 entirely; if C = 0, render P5b as skipped.

Load ../shepherd-driver/references/mergeability-gate.md when entering this phase -- it holds the binding step-by-step (probe CLI flags, retry policy, four-way partition, trust-but-verify re-probe). The contract summary:

• 5a (read-only): probe every Phase-4 ready PR via S7 DETERMINISTIC TOOL BRIDGE (gh pr view --json with the S7 mergeability fields -- full flag list in mergeability-gate.md). Skip triaged-deferred rows. Partition CLEAN / UNSTABLE / HAS_HOOKS (verified-ready) from BEHIND / DIRTY / CONFLICTING (route to 5b). BLOCKED is not a conflict.
• 5b (fan-out, one subagent per CONFLICTING PR): print dispatch table, spawn resolve-conflicts-<pr> subagents using ../shepherd-driver/assets/conflict-resolution-prompt.md. Each owns its PR end-to-end: rebase, faithful conflict merge, lint silent, push with --force-with-lease (NEVER bare --force), re-probe, post the single resolution-confirmation comment. Returns are conflict_resolution_return matching ../shepherd-driver/assets/completion-schema.json.
• 5c (read-only): trust-but-verify re-probe; partition into the schema's four conflict_resolution_return statuses; update the table.

Phase 6 - final report

Re-render with every phase done (or blocked where the human-escalation queue is non-empty). Render assets/final-report-template.md: per-issue verdict, PR link, post-gate status (the template's status set), and subagent session refs. Phase-1.5-demoted rows land in the template's "Recommend close as out-of-scope" partition, each citing the principle that fired.

Use clickable GitHub links (issue + pull URLs under github.com/microsoft/apm) and @<author> profile links, not plain issue numbers.

After the report renders, tear down ONLY the worktrees this run created (git worktree remove each slug in the worktree column); leave branches on origin for the open PRs.

Bundled assets

This skill bundles ONLY the assets unique to its triage-and-batch orchestration. Everything PR-drive related is owned by the composed shepherd-driver sibling, loaded from ../shepherd-driver/, not duplicated here.

• assets/verdict-schema.json -- JSON schema for the TWO BBS-owned subagent return shapes (triage_return, strategic_alignment_return). Schema-validate every return (S4).
• assets/ground-truth-table.md -- canonical table template (issue | verdict | pr | pr_in_flight | author | head_repo | head_branch | maintainer_can_modify | worktree | status | strategic_verdict | strategic_rationale | notes).
• assets/triage-prompt.md -- WAVE 1 spawn body.
• assets/strategic-alignment-prompt.md -- WAVE 1.5 spawn body (loads apm-ceo persona + PRINCIPLES.md).
• assets/fix-prompt.md -- WAVE 2 greenfield-fix spawn body.
• assets/final-report-template.md -- user-facing report shape.
• assets/progress-diagram.md -- mermaid progress diagram, color contract, dispatch-table render rules (Phase 1, 1.5, 3, 4, 5b).
• references/strategic-alignment-gate.md -- Phase 1.5 step-by-step (external-dep probes, fail-open semantics, deferred-PR strategic-rejection subagent). Load WHEN ENTERING PHASE 1.5.
• references/invariants.md -- full binding text of the 18 architecture invariants. Load BEFORE PLANNING PHASE 0.

Composed from shepherd-driver (loaded by relative path, NOT bundled): shepherd-driver-prompt.md (Phase 4 drive), conflict-resolution-prompt.md (Phase 5b), completion-schema.json (driver + resolution returns), scripts/owner_touch_gate.py (terminal functional-evidence gate), references/mergeability-gate.md (Phase 5 gate) -- all under ../shepherd-driver/.

Operating contract for the orchestrator thread

The orchestrator loop, beyond the invariant anchors above:

• Before each phase: re-read plan.md ground-truth table. After each subagent return: schema-validate, update the table, write it back.
• Delegate every PR-side write to the responsible subagent; the orchestrator never posts to a PR and never flips merge state.
• Render the progress mermaid + live table at every phase boundary, and the dispatch table before every fan-out (assets/progress-diagram.md).

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).
• Driving a single PR to merge without a batch (use shepherd-driver directly).
• Auto-merge or auto-label. The orchestrator does not flip merge state; the maintainer ships.