Skip to content

issue-triage.md

Latest commit

 

History

History
94 lines (66 loc) · 4.43 KB

issue-triage.md

File metadata and controls

94 lines (66 loc) · 4.43 KB
Raw

Issue Triage Loop

Goal: Continuously discover, deduplicate, prioritize, and label incoming issues, feature requests, and discussions so the team (and other loops) always have a clean, actionable top-of-queue. Pure report / proposal mode in week one. Extremely low risk, high leverage.

Scheduling

Recommended:

  • /loop 2h or 1d (morning + end of day for busy repos)
  • GitHub Action on issues / discussion events + scheduled fallback
  • Pairs beautifully with Daily Triage (this loop feeds the "what should I work on" report)

This is an excellent always-on, low-cost companion loop.

Required Skills

  • issue-triage — Scans open issues, discussions, and (optionally via MCP) Linear / Jira. Dedupes, extracts signals (labels, comments, linked PRs, age, reactions), proposes priority + suggested labels + one-sentence summary.
  • loop-verifier (light or human) — Sanity check on the proposed triage actions / new labels before anything is applied.

State

Filename: issue-triage-state.md

Compact rolling view of the current backlog health:

# Issue Triage State
Last run: 2026-06-09 09:15 UTC
Open actionable: 14 (was 17)
New since last run: 3
Needs human: 2 (one potential duplicate of #412, one unclear spec)

## Top 5 (by loop score)
- #487 (bug, p1, 2d old) — "Crash on export with large files" — suggested: bug + needs-repro + area:export
- ...

The loop prunes closed/merged items and only keeps "needs attention" items.

How the Loop Runs (Typical Cycle)

  1. Discover new/updated issues + discussions since last run (or all open if first run).
  2. For each: summarize intent, detect duplicates (title + embedding hints or simple text match), pull signals (age, author, linked PRs, reactions, existing labels).
  3. Score / bucket: P0 (security, prod breakage), P1 (high impact + clear), P2, P3, needs-info, duplicate.
  4. Write or update a clean prioritized list + suggested label set + short "why this matters" into the state file (and optionally a comment on the issue itself as "Loop triage note").
  5. Verifier (or human) reviews only the "needs human" bucket and any proposed label changes on sensitive areas.
  6. Record run, prune resolved items, update counts.

Verification Strategy

  • The loop never auto-labels or closes in L1.
  • In L2 it can apply allowlisted labels only (e.g. area:*, needs-repro) after verifier passes.
  • Human always owns P0/P1 assignment for the first weeks and for anything touching auth, payments, security, or public API.

Human Handoff Points

  • Any issue touching security, auth, billing, or infra
  • Duplicate detection that is uncertain (>30% chance wrong)
  • Issues older than N days that the loop wants to close as "stale" (human confirms)
  • When > X new issues appear in a single run (context overload signal)

Tool-Specific Notes

Grok Build TUI:

/loop 2h Run issue-triage skill. Read issue-triage-state.md first. Produce updated state + suggested labels for new items only. No auto-label or close. Escalate anything ambiguous.

Claude Code:

/loop 2h $issue-triage — update issue-triage-state.md. Propose labels only on allowlisted areas. Human review for P0/P1.

Codex: Automation every 2h or on issues event: run issue-triage → update state. Report mode.

GitHub Actions: See examples/github-actions/ for a starter workflow that can react to issue events + scheduled run.

Failure Modes & Mitigations

Failure Mitigation
Over-prioritizing noisy reporter Weight by signals the team actually cares about (reactions, linked PRs, internal +1s). Human overrides recorded in state.
Duplicate false positives Conservative matching + always surface "possible duplicate of #NNN" for human confirmation in L1.
Alert fatigue on every new issue Only notify human for the "needs human" slice. Everything else lives in the state file that Daily Triage or the engineer reads.

Success Metrics

  • Reduction in time from issue open → first meaningful label or "needs info" comment.
  • % of issues that have a clear priority within 24h.
  • Engineer-reported "I always know what the top 5 things are" score (qualitative, from state file reviews).
  • Number of duplicates caught before two people start working on them.

See also: Daily Triage (this loop is a feeder), Multi-Loop Coordination, and the Loop Design Checklist.