process-issues

name

process-issues

description

Run one issue-triage tick on the current repo's open issues, then stop. Scan untriaged issues, classify them (type: bug/feature/task), reproduce bugs, and route each through the canonical triage state machine: needs-info / ready-for-agent (with an agent brief) / ready-for-human, or park a wontfix/duplicate/out-of-scope belief in needs-triage for the maintainer. Does one tick then stops, so it composes with /loop for a recurring issue loop (e.g. `/loop /process-issues`, `/loop 1h /process-issues`). Never closes an issue, never applies wontfix; those stay the maintainer's call. GitHub-only (uses `gh`). The autonomous sibling of the interactive /triage skill. Use when the user wants to triage, classify, or process open issues, prepare issues for AFK agents, or set up a recurring issue-triage agent.

Process issues (one tick)

One pass over the repo's open issues per invocation, then stop. Compose with /loop for recurrence (/loop /process-issues, /loop 1h /process-issues); /loop owns pacing. Never schedule yourself.

This is the autonomous sibling of the interactive /triage skill: it runs the same state machine and reuses the triage skill's bundled references (its AGENT-BRIEF.md template, OUT-OF-SCOPE.md knowledge base, and needs-info notes template) instead of duplicating them. The difference is that /triage waits for the maintainer at each step; this pass acts autonomously and parks anything that needs a human.

State derives entirely from GitHub (labels, comment timestamps), so a tick is idempotent: an empty queue costs one gh issue list and exits.

Rails

• Never close an issue, never apply wontfix. Those are the maintainer's call. When this pass believes an issue is wontfix, a duplicate, out of scope, or a "do we even want this" scope question, it does not close it: it leaves a disclaimer-prefixed comment with the reasoning (and any .out-of-scope/ match or duplicate link) and parks it in needs-triage for the maintainer to confirm-and-close. wontfix is a recommendation, never an action.
• Every comment starts with a disclaimer: > *This was generated by AI during triage.*.
• Skip issues owned by another active loop. If another dispatcher already drives an issue (it is in that loop's queue), leave it untouched.

0. Preflight

• Abort if not a git repo, or if there is no GitHub remote. This skill is GitHub-only (gh, issues).
• Detect optional substrate; use what exists, skip what doesn't:
  • Triage labels + wiring (docs/agents/triage-labels.md mapping the canonical roles needs-triage / needs-info / ready-for-agent / ready-for-human / wontfix, and an issue type: axis). If absent, offer to run /setup-github-labels and stop: without state labels the tick can read but cannot record an outcome.
  • .out-of-scope/ directory. If present, read it during context-gathering (see the triage skill's OUT-OF-SCOPE.md); if absent, skip out-of-scope matching.

States

This pass routes each issue to exactly one canonical state (label strings come from triage-labels.md). Every triaged issue also carries one category role (type: bug / type: feature / type: task).

• needs-info: underspecified or unreproducible; waiting on the reporter.
• ready-for-agent: fully specified, behind the strict gate below, with an agent brief. The handoff to an AFK agent (implemented by /implement-issues).
• ready-for-human: wanted, but a human must implement it (judgment, access, or a design decision).
• needs-triage: the parking spot for the maintainer. A wontfix / duplicate / out-of-scope / scope-call belief lands here with a comment. This pass never re-picks it.

Tick algorithm

1. Build the queue. Two buckets:

   • Open issues with no triage state label (never triaged, this pass's turn).
   • needs-info issues where the reporter has replied since the last triage note (re-evaluation needed).

   gh issue list --state open --json number,title,labels,author,createdAt,updatedAt \
     --jq '[.[] | {number, title, labels: [.labels[].name], author: .author.login, createdAt, updatedAt}]'
   

   Skip issues already wearing ready-for-agent / ready-for-human / wontfix, and do not re-pick needs-triage (that is the parking spot, not a work queue).

2. Process up to ~5 issues this tick, oldest-first, each through the pipeline below, then stop. /loop drains a larger backlog over later ticks.

3. Report. A short dashboard: each issue processed and the state applied, recommendations parked for the maintainer, anything needing a human call. /loop reads this to pace the next run.

Per-issue pipeline

1. Gather context in a subagent (keep the main loop context clean): read the issue body, comments, labels, reporter, and dates; parse prior triage notes so resolved questions are not re-asked; read .out-of-scope/; quick-search open issues for a likely duplicate; explore the codebase. For bugs, attempt reproduction (trace the code, run tests). A confirmed repro makes a far stronger brief; a failed or impossible repro is a strong needs-info signal.

2. Classify the category → type: bug / type: feature / type: task.

3. Route to a state:

   • Out-of-scope match or duplicate of an open issue → comment linking the prior .out-of-scope/ entry or the original issue, then park needs-triage. Never close.
   • Underspecified / repro failed / missing information → needs-info, using the triage skill's needs-info notes template. Capture everything already established so the work is not lost; ask the reporter specific, actionable questions. This is the autonomous substitute for /triage's maintainer-grilling: ask the reporter, do not block on a human.
   • Passes the strict gate → ready-for-agent with an agent brief written per the triage skill's AGENT-BRIEF.md. The gate requires all of: one reasonable interpretation, a complete brief with concrete testable acceptance criteria, verifiability by cheap or existing tests, and no product/design decision or human-only access required.
   • Wanted but a human must build it (judgment, access, design decision) → ready-for-human, same brief structure, noting why it cannot be delegated.
   • A "do we even want this" scope call → park needs-triage with the reasoning.

   When in doubt, escalate. Prefer ready-for-human or needs-triage over ready-for-agent: handing an AFK agent an underspecified brief is the failure mode this gate exists to prevent.

Composition

Spin-off issues from /process-prs land unlabeled, so this pass picks them up and triages them on its next tick (escalations from /kaizen-codebase arrive already labeled needs-triage and are left for the maintainer, not re-picked here). An issue this pass marks ready-for-agent is the handoff to /implement-issues (this pass does not write code or open PRs itself); the resulting PR is then handled by /process-prs.