/issues

name: issues
disable-model-invocation: true
description: GitHub-issue marathon - triage open issues, then run agent-ready ones to merge with Agent Teams
argument-hint: [scope-label] (optional - narrows which open issues are considered; default: all open issues)

<!-- floor:cold-verify-completion -->

GitHub Issue Marathon

> Thin orchestrator. Triages open issues, then delegates execution of `agent-ready` issues > to the marathon skill (same engine as `/tm`).

Configuration

Read the repo's CLAUDE.md `## Marathon Configuration` (GitHub Issues subsection) for label names, with defaults:

• Agent-ready label: `agent-ready`
• Needs-triage label: `needs-triage`
• In-progress label: `in-progress`
• Issue exclude labels: (none)

Also read base branch, required approvals, and bot-reviewer rules (shared with `/tm`).

Phase 0: Capability Detection

echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS   # set $TEAMS_AVAILABLE (true if "1")

Routing

ORG=$(gh repo view --json owner --jq '.owner.login')
REPO=$(gh repo view --json name --jq '.name')
# Optional scope filter from $ARGUMENTS — narrows the issue universe; routing still applies within it.
SCOPE_LABEL="$ARGUMENTS"   # empty = all open issues
FILTER=(); [ -n "$SCOPE_LABEL" ] && FILTER=(--label "$SCOPE_LABEL")
READY=$(gh issue list --label "agent-ready" "${FILTER[@]}" --state open --json number --jq 'length')

• `READY > 0` → **Marathon mode.** Work ONLY the `agent-ready` issues. Do NOT assess or

modify untagged issues — the human has curated the queue by tagging.

• `READY == 0` → **Triage mode** (below).

Triage Mode (no agent-ready issues exist)

Enumerate open issues minus the exclude labels:

gh issue list "${FILTER[@]}" --state open --json number,title,body,labels | \
  jq '[.[] | select((.labels[].name) as $l | ($l | IN("<exclude-labels>")) | not)]'

If `$ARGUMENTS` (a scope label) was given, only issues carrying it are considered; routing still applies within that subset.

Triage is a planning pass, not a labeling pass. It runs once over the whole issue set, in this order, and every write it makes shows up in the report the human approves:

1. **Promote on Confirmation** - fold in answers the human gave since the last run. 2. **Research Pass** - resolve what the repository can answer before asking anything. 3. **Overlap Sweep** - hold back issues that collide with open PRs; record issue-to-issue collisions as edges or hot-file notes. 4. **Size by Judgment** - decide one PR or several, and propose any decomposition. 5. **Dependency Authoring** - write the ordering as native `blocked_by` edges. 6. **Triage Report** - apply every label write at once, then render labels, decomposition tree, execution order, overlaps; STOP.

An issue is `agent-ready` only when it survives all of steps 2 to 4: clear after research, no unresolved overlap, and sized to one PR (or approved as a decomposed parent). Everything else stays or becomes `needs-triage`. Research and sizing read widely, so fan them out with subagents (the `Agent` tool); never teammates.

Steps 1 to 4 decide the label of each issue that exists at the start of the pass but do not write it: the verdict needs all four inputs, so every `agent-ready` / `needs-triage` label change on those issues happens in one write at the Triage Report step. Creating an approved decomposition is a separate phase after approval that labels its own children and parent (see Size by Judgment). An interrupted pass therefore never leaves an issue `agent-ready` while it overlaps an open PR. Comments, body edits and dependency edges are written where they are decided.

Promote on Confirmation

Start with issues already labeled `needs-triage` that carry a triage comment with a recommended reading, or a decomposition proposal comment (marker `<!-- triage:decomposition-proposal -->`, see Size by Judgment). A human reply approving that proposal on the issue counts as approval of the decomposition and triggers its creation phase. If a human reply after that comment confirms or corrects it ("yes, reading A" is enough), fold the confirmed answers into the issue body (append a `Clarified scope` section with the confirmed scope and acceptance criteria) or, when the body is the author's to keep, into a marker-tagged issue comment: a new comment whose first line is the HTML-comment marker `<!-- triage:clarified-scope -->`. The marker, not any UI pinning, is what makes it durable: the implementing teammate and every later run find the clarified contract by grepping for it, never by re-interpreting the thread. The issue's verdict becomes `agent-ready` (label swapped from `needs-triage` at the Triage Report step) unless the same pass's Overlap Sweep or Size by Judgment holds it back:

gh issue edit <N> --body-file <body-plus-clarified-scope.md>   # issue body route
gh issue comment <N> --body-file <clarified-scope.md>          # marker comment route; first line is the marker

A correction that opens a new question is not a confirmation: run the Research Pass on the new question and keep `needs-triage`. No reply means no change.

Research Pass

Before any question reaches a human, research it. For each issue whose scope, acceptance criteria, or intent is unclear, run an understand-style pass over what the ambiguity touches: the code and tests, open and merged PRs (`gh pr list --state all --search "<terms>"`), and the issue history (linked, referenced, and closed issues). The primitive is the `/understand` command (`commands/understand.md`, relative to the plugin root): define the terms, separate the explicit need from the implicit one, and bound the scope, grounded in what the repository shows. Spawn one research subagent per ambiguous issue (or per subsystem for a wide one) so the pass runs in parallel.

Any question the repository answers is answered, not asked. What the code does now, whether a constraint is real, which reading matches existing behaviour