AGENT SKILL

issue-triage

Analyze open GitHub or GitLab issues from `forge-cli inbox`, classify readiness versus blockers, and recommend an execution order; read-only unless the user explicitly asks for follow-up.

License 许可
MIT
最近更新
2026-08-29
Stars
★ 0
Forks
0

01 前言 Front Matter

name
issue-triage
description
Analyze open GitHub or GitLab issues from `forge-cli inbox`, classify readiness versus blockers, and recommend an execution order; read-only unless the user explicitly asks for follow-up.

03 SKILL.md 正文

Issue Triage

Read-only issue work selection for deciding what an agent can do now, what is blocked, and what order to recommend.

Contract

Prereqs:

  • Run inside the target provider-backed git repository, or pass explicit --repo and --provider options to forge-cli.
  • forge-cli >=1.11.2 is installed from the released nils-cli package and available on PATH.
  • Provider authentication is available for non-dry-run inbox and issue reads.
  • For implementation handoff, the normal implementation, issue follow-up, or PR/MR workflow is available.
  • Shared close/comment rules in ../issue-follow-up/references/issue-lifecycle.md are known for any handoff.

Inputs:

  • User request to review current open issues, choose what to work on next, identify blocked items, or recommend execution order.
  • Optional provider, repository, kind, item-type, limit, or GitLab host.
  • Optional instruction to include PR/MR work; otherwise focus on issues.

Outputs:

  • A concise triage report with candidate issues grouped by readiness.
  • A recommended execution order with reason, risk, blocker, and first action for each ranked issue.
  • Clear handoff suggestion when an issue should move into issue-follow-up, implementation, PR/MR delivery, or comment-only maintenance.

Failure modes:

  • forge-cli inbox fails because provider auth, permissions, network, or host configuration is unavailable.
  • Inbox data is too thin to classify an issue and issue detail reads fail.
  • Issue state is ambiguous enough that proceeding would risk wrong provider comments, code changes, or prioritization.

Entrypoint

Start with the normalized inbox issue surface:

forge-cli inbox list --item-type issue --format json
forge-cli inbox next --item-type issue --format json

Pass provider and repository selectors through when needed:

forge-cli inbox list --provider github --repo owner/name --item-type issue --format json
forge-cli inbox list --provider gitlab --gitlab-host gitlab.example.com --item-type issue --format json

When the inbox record does not contain enough context to judge readiness, read issue detail before deciding:

forge-cli issue view "$ISSUE" --format json

Workflow

  1. Determine scope:
    • Default to open issues only: --item-type issue.
    • Include PR/MR only when the user asks for broader work inbox triage.
    • Keep provider selection inbox-local; use --provider only when the user or repository context narrows the target.
  2. Collect candidates:
    • Run forge-cli inbox list --item-type issue --format json.
    • Run forge-cli inbox next --item-type issue --format json for the CLI's bounded ranking signal.
    • If a provider partially fails, continue with successful providers and report the failed provider as a data gap.
  3. Enrich only as needed:
    • Read the top candidates or ambiguous items with forge-cli issue view "$ISSUE" --format json.
    • Inspect body, labels, assignees, latest comments when available, linked PR/MR references, and explicit blocker language.
  4. Classify each candidate:
    • ready-now: scope and next action are clear; no external decision, permission, CI, review, or missing-data blocker is visible.
    • needs-clarification: outcome, acceptance, owner, or first action is unclear enough that execution should not start yet.
    • blocked: waiting on external decision, user input, provider access, review, CI, release, upstream issue, credentials, or unavailable evidence.
    • stale-or-low-value: old, low-signal, duplicate-looking, or weakly tied to the current repo or user request.
  5. Rank recommendations:
    • Prefer ready-now issues that are small, well-scoped, high-impact, and have clear validation.
    • Prefer unblocking comments before implementation when a blocker can be resolved with one concise question or checkpoint.
    • Deprioritize issues that require broad planning, destructive operations, unavailable credentials, or multi-repo coordination unless the user asked for that scope.
  6. Report with evidence discipline:
    • Separate facts from issue data, inferences from those facts, assumptions, and open questions.
    • For each recommended issue, include the issue URL or number, readiness bucket, why now, first action, and the next workflow to use.
    • Do not post comments, close issues, create branches, or start implementation unless the user explicitly asks.

Handoff

  • Use issue-follow-up when the next action is provider-visible issue maintenance, a blocker checkpoint, or a durable follow-up comment.
  • Use normal implementation and PR/MR workflows when a ready-now issue has a clear code or docs change and validation path.
  • If the best next action is a broader plan bundle or dispatch lane, say that explicitly instead of silently expanding triage into planning.

Boundary

issue-triage is a read-only selection and recommendation workflow. It uses forge-cli inbox as the candidate source and forge-cli issue view as optional context enrichment. It does not replace issue-follow-up, mutate provider state, or implement the selected issue unless the user explicitly asks for that next step.

Shared rules for follow-up comments and closure live in ../issue-follow-up/references/issue-lifecycle.md.

04 同仓库更多 Skills