issue-triage

Files (14)

• SKILL.md
• categories.md · reference/
• decision-tree.md · reference/
• relevance-checks.md · reference/
• skip-patterns.md · reference/
• transfer-targets.md · reference/
• triage-save.sh · scripts/
• triage-status.sh · scripts/
• escalation-format.md · templates/
• responses.md · templates/
• cross-machine-state.md · workflows/
• escalation.md · workflows/
• self-evolution.md · workflows/
• triage-session.md · workflows/

SKILL.md (first lines)

# Issue Triage

Systematically process GitHub issue backlogs with intelligent categorization, relevance verification, and self-evolving improvements.

## Quick Start

```
1. Load repo context (labels, templates, docs)
2. Check cross-machine state (if available)
3. Fetch batch of oldest untriaged issues (skip bots, skip in-flight PRs)
4. For each issue: verify → categorize → act → log
5. Report summary + escalations
6. Save state and suggest systemic improvements
```

## Contents

| Document                                                               | Purpose                                       |
| ---------------------------------------------------------------------- | --------------------------------------------- |
| [SKILL.md](./SKILL.md)                                                 | This file - overview and quick reference      |
| [reference/decision-tree.md](./reference/decision-tree.md)             | Full decision flowchart for issue handling    |
| [reference/categories.md](./reference/categories.md)                   | Issue categories, labels, and signals         |
| [reference/relevance-checks.md](./reference/relevance-checks.md)       | How to verify if issues are still valid       |
| [reference/transfer-targets.md](./reference/transfer-targets.md)       | Where to transfer misplaced issues            |
| [reference/skip-patterns.md](./reference/skip-patterns.md)             | Issues to skip during triage                  |
| [workflows/triage-session.md](./workflows/triage-session.md)           | Step-by-step triage session workflow          |
| [workflows/self-evolution.md](./workflows/self-evolution.md)           | Pattern detection and improvement suggestions |
| [workflows/escalation.md](./workflows/escalation.md)                   | When and how to escalate to humans            |
| [workflows/cross-machine-state.md](./workflows/cross-machine-state.md) | Track triage progress across sessions         |
| [templates/responses.md](./templates/responses.md)                     | Canned responses for common situations        |
| [templates/escalation-format.md](./templates/escalation-format.md)     | Format for escalation reports                 |

## Core Principles

1. **Process oldest to newest** — Start with the oldest untriaged issues
2. **Verify before acting** — Check if code/feature still exists
3. **Use existing semantics** — Use repo's existing labels; verify before using
4. **Transfer, don't close** — Misplaced issues go to the right repo
5. **Escalate uncertainty** — Low confidence → ask human
6. **Learn from patterns** — Suggest docs/template/label improvements
7. **Be idempotent** — Skip already-processed issues, don't duplicate comments

## Issue Decision Quick Reference

```
Security issue?        → Escalate immediately, no public comment
Bot-generated?         → Skip (CodeRabbit, Dosu auto-issues)
Has in-flight PR?      → Skip (note PR exists)
Wrong repo?            → Transfer (don't close)
Old version reported?  → Request version verification
Incomprehensible?      → Request clarification
Code doesn't exist?    → Close with explanation
Duplicate?             → Close with reference
Already fixed?         → Close with reference to fix
Working as designed?   → Close as wontfix with explanation
Workaround exists?     → Keep open if underlying bug valid
Clear category?        → Apply label
Enough info?           → Ready for prioritization
Uncertain?             → Escalate
```

## Skip Patterns

Skip these issues entirely:

- **CodeRabbit auto-issues**: author `coderabbitai[bot]`
- **Issues with in-flight PRs**: Note the PR, skip triage
- **Recently active with maintainers**: Being worked on
- **Already assigned**: Someone owns it

## Version Staleness

Request verification when reported version is >3 minor versions old:

- Use comment patterns: "Version check:" and "This was reported on v"
- Reference specific PRs that may have fixed the issue

## Transfer vs Close

**Transfer** when issue belongs elsewhere:

```bash
gh issue transfer <number> <target-repo>
```

**Close as wontfix** when:

- Working as designed
- User misunderstanding
- Workaround IS the permanent solution

**Keep open** when:

- Workaround is temporary
- Underlying bug still exists
- API improvement still needed

## Confidence Thresholds

| Confidence | Action                          |
| ---------- | ------------------------------- |
| >80%       | Act automatically               |
| 50-80%     | Act but flag for review         |
| <50%       | Escalate, suggest but don't act |

## Dosu Bot Integration

If Dosu has commented:

1. Parse Dosu's analysis as starting context
2. Use linked PRs/issues for cross-referencing
3. Don't duplicate questions Dosu already asked
4. Validate Dosu's code suggestions against current codebase (can be outdated)

## Key Commands

Before starting, gather context:

```bash

From DrJKL/ticket-to-pr-pipeline, MIT.

More from DrJKL/ticket-to-pr-pipeline