issue-sweep

issue-sweep — Sweep & Handle Open GitHub Issues

Overview

Collect open GitHub issues (optionally filtered by label), triage out the ones that need careful human judgment, confirm the plan once, then drive each remaining issue to completion with /big-plan -m -a.

There is exactly one human checkpoint: the confirmation in Step 3. Everything after it runs autonomously per -a.

Options

Flag	Alias	Meaning	Example
-f	--filter	Keep only issues that carry the given label	/issue-sweep -f mac
-ex	--exclude	Drop issues that carry the given label	/issue-sweep -ex deferred

• Each flag accepts a comma-separated list (-f a,b) or may be repeated.
• --filter maps to gh's native --label (AND semantics — an issue must carry every filter label). --exclude is applied client-side — an issue is dropped if it carries ANY excluded label.
• Flags compose: /issue-sweep -f agent-found -ex deferred.
• No defaults. With no flags, every open issue is a candidate.

Step 1: Collect candidate issues

Build the list from the parsed flags. Start from open issues, add one --label per filter label, then drop excluded labels client-side.

# -f agent-found -ex deferred  →
gh issue list --state open --label agent-found \
  --json number,title,labels,url --limit 200

Then drop any issue whose labels include an excluded label. If the remaining set is empty, report "No issues to sweep" and stop.

With no -f, the candidate set is all open issues — surface the count to the user so the scale of the sweep is clear before triaging.

Step 2: Triage — handle vs skip

For each candidate, read its concrete detail with /gh-fetch-issue <number> (this downloads embedded screenshots so they are actually readable — plain gh issue view cannot show them). For a large candidate set, delegate the reading to parallel subagents (one per chunk) that return a compact #N | classification | one-line scope | reason per issue — keep the judgment yourself.

Classify each issue into one of three buckets:

• Handle — well-scoped, normal-sized work the autonomous chain can finish safely. This includes "verify X" tasks that are checkable locally (no auth, no deployed env, no external service, not a subjective judgment call) — those are handled by verifying directly and closing (see Step 4), not by /big-plan.
• Skip — design/scope — leave it open; suggest a deferred label (do not auto-apply it). Skip here when the issue is:
  • a large multi-major dependency / version bump (e.g. "bump X from 1 → 4"),
  • a super-big epic (an [Epic] issue, or one that would fan out into many sub-issues),
  • any change whose correctness hinges on a design decision a human should make.
• Skip — needs human verification — a verification ([Mac]/manual) task that cannot be auto-verified locally: it requires authenticated login, a deployed/production environment, an external third-party service (e.g. an X/Twitter card validator), or a subjective visual / aesthetic / cultural-fidelity judgment at scale. Leave it open and auto-apply the needs-human-verified label (create the label once if it does not exist — see Step 3a). This label is applied automatically; deferred is only ever suggested.

When unsure whether something is "too big," lean toward a Skip bucket and surface it in Step 3 rather than autonomously running it.

Step 3: Confirm with the user

Present a triage table before doing anything irreversible:

• Will handle: #N — title — one-line scope
• Will skip: #N — title — reason

Get explicit confirmation (use AskUserQuestion) before launching. This is the single human checkpoint.

Step 3a: Label the "needs human verification" skips

For every issue in the Skip — needs human verification bucket, apply the needs-human-verified label. Create the label once if it is missing:

gh label create "needs-human-verified" --color "1D76DB" \
  --description "Verification task that can't be auto-verified locally; needs a human (auth/deploy/subjective)"
# then, per issue:
gh issue edit <N> --add-label "needs-human-verified"

(Keep the description ≤ 100 characters — GitHub rejects longer, and multi-byte dashes inflate the count.) Do not apply deferred here — that one stays a suggestion in the final report.

Step 4: Handle each issue via /big-plan -m -a

Process the handle list one issue at a time — each issue is independent, so batching them into a single /big-plan run would conflate unrelated work into one epic. (Two issues covering the obviously-same surface may be grouped, but one-at-a-time is the default.)

For each issue:

1. Invoke /big-plan -m -a <issue-url>.

• -a runs plan → create sub-issues → implement → review autonomously.
• -m merges the resulting PR into the invocation branch, then cleans up and watches base CI (auto-fixing on red).

2. Let it finish before starting the next issue.

Notes:

• Run the sweep from the branch where this work should land (e.g. a long-lived release-candidate branch), not directly on a protected production branch.
• "Verify X" tasks that are locally checkable (the Handle bucket) do not go through /big-plan — running it on a pure-verify issue forces an empty PR. Instead, spin up the app and verify directly (/verify-ui or /headless-browser, driving the real running app). Close the issue with a short evidence-backed note if it passes; only if verification reveals a real defect do you open a fix-PR (via /x-as-pr or /big-plan). For a batch of independent UI verifications, delegate each (or each cluster) to a parallel subagent that drives the running dev server and returns a PASS/FAIL verdict with concrete evidence (computed styles, scroll numbers, screenshots) — then you close/fix based on the verdicts. (Browser gotcha: a Playwright launchPersistentContext with a shared profile dir can break an app's MSW boot; prefer launch() + newContext(), or the headless-browser skill's per-session profile.)
• If a /big-plan run fails or stalls, stop, report which issue, and let the user decide before continuing the rest.

Step 5: Final report

Summarize the sweep:

• Handled & merged: #N …
• Verified & closed (no code change needed): #N …
• Skipped — needs human verification (labeled needs-human-verified): #N …
• Skipped — design/scope (suggest deferred): #N …
• Failed / needs attention: #N …