triage

---
name: triage
description: "Issue state-machine classification with explicit transition rules. Use when 'triage issue X', 'state of #N', 'classify issues', 'transition issue', or batch-cleaning Forgejo issues."
mode: [personal, all]
effort: medium
version: 1.1.0
tier: [admin]
attribution: "Cherry-picked from mattpocock/skills (MIT, see CREDITS.md). Re-merged upstream 8 practical workflow scenarios + ported AGENT-BRIEF.md + OUT-OF-SCOPE.md companion files: 2026-05-03 (per memory/audit-mattpocock-drift-2026-05-03.md)."
see_also: [forgejo-pr, feature-board, forgejo-worktree]
thinking_mode: adaptive
---

# Triage

> Issue lifecycle skill : classifier explicitement chaque issue dans une **state machine** finie, avec **transitions deterministes** et **labels Forgejo auto-applies**. Anti-pattern qu'on evite : le bucket "open" qui contient 200 issues melangees (vraies bugs, demandes-de-clarification, blockers, dejà-fixed).

## When to Invoke

### Manual triggers (user-initiated)

- "triage issue #123" / "triage cette issue"
- "state of #N" / "quel est l'etat de l'issue N"
- "classify all open issues" / "batch triage"
- "transition #N to in-progress"
- "/atlas triage <num>" / "/atlas triage --batch"
- "report on issue states"

### Automatic triggers (agent self-detection)

Invoque proactivement quand :
- > 30 issues open dans le repo (signal sedimentation)
- Issue ouverte > 14 jours sans label de state
- User mentionne "tellement d'issues, on s'y perd"
- Avant un sprint planning (clean state pour triage humain)

## State Machine (6 states + transitions)

```
            ┌──────────┐
            │   open   │   <-- default state, no triage label
            └────┬─────┘
                 │
       ┌─────────┼─────────────┬──────────────┐
       v         v             v              v
 ┌──────────┐ ┌─────────┐ ┌─────────────┐ ┌────────┐
 │needs-info│ │ blocked │ │in-progress  │ │ closed │
 └────┬─────┘ └────┬────┘ └──────┬──────┘ └────────┘
      │            │              │
      ├────────────┴──────────────┤
      │                           v
      │                    ┌──────────┐
      │                    │  review  │
      │                    └────┬─────┘
      │                         │
      │                ┌────────┴─────────┐
      │                v                  v
      │         (changes-requested)   ┌──────┐
      │           -> in-progress      │ done │ <-- terminal
      │                               └──────┘
      └ (clarification received)
        -> in-progress
        -> closed (no longer relevant)
```

### Allowed transitions

| From          | To (allowed)                         | Auto-comment template                         |
|---------------|--------------------------------------|-----------------------------------------------|
| `open`        | needs-info, blocked, in-progress, closed | "Triaged → {to}. {rationale}"             |
| `needs-info`  | open, in-progress, closed            | "Clarification {received/timeout}. → {to}"    |
| `blocked`     | in-progress, closed (won't fix)      | "Unblocked by {dep}. → {to}" or "Closing as won't-fix" |
| `in-progress` | review, blocked                      | "PR opened → review" or "Blocked by {dep}"    |
| `review`      | in-progress (changes requested), done | "Changes requested" or "Approved + merged → done" |
| `done`        | (terminal)                           | (no further transition)                       |

### Forbidden transitions (validator rejects)

- `done` → anything (re-open via NEW issue with `relates-to:#N`)
- `open` → review (must pass through in-progress)
- `closed` → anything (terminal, like `done`)

## Forgejo Labels (auto-applied)

| State           | Label              | Color   |
|-----------------|--------------------|---------|
| open (default)  | (no state label)   | -       |
| needs-info      | `state:needs-info` | #FBCA04 |
| blocked         | `state:blocked`    | #B60205 |
| in-progress     | `state:in-progress`| #1D76DB |
| review          | `state:review`     | #5319E7 |
| done            | `state:done`       | #0E8A16 |

Labels are created on first triage in a repo (idempotent). Existing user labels (priority, type, etc.) are preserved.

On every transition, an auto-comment is posted with:
1. The transition (`open → needs-info`)
2. The rationale (1-2 sentences)
3. The triggering actor (`atlas triage` or username)
4. Timestamp (UTC)

## CLI

### Single-issue classification

```bash
atlas triage <issue-num>
# Reads issue title + body + comments, classifies into one of 6 states.
# Asks for confirmation before applying label + comment.
# Example: atlas triage 142
```

### Batch classification

```bash
atlas triage --batch <repo>
# Iterates all open issues without state label.
# Uses LLM-as-judge for ambiguous cases (heuristics first, LLM fallback).
# Dry-run by default; --apply to commit.
# Example: atlas triage --batch axoiq/synapse --apply
```

Heuristic ladder (cheap → expensive) :
1. Title regex (e.g., `\bquestion\b` → needs-info, `\bblocked by\b` → blocked)
2. Body length + structure (no repro steps + < 200 chars → needs-info)
3. Linked PR exists → in-progress or review
4. Last comment age > 14 days + no activity → likely stale needs-info
5. LLM-as-judge fallback (Haiku) for the ~20% remaining

### Manual transition

```bash
atlas triage --transition <issue-num> <new-state> [--rationale "..."]
# Validates transition against state machine rules.
# Refuses forbidden transitions with clear error.
# Example: atlas triage --transition 142 in-progress --rationale "Started PR #145"
```

### State-distribution report

```bash
atlas triage --report <repo>
# Generates markdown report:
# - Histogram of states (with counts)
# - Stale issues per state (> 14d in same state)
# - Transition heatmap (last 30d)
# - Outliers needing manual review
# Output: stdout + memory/triage-report-<repo>-<YYYY-MM-DD>.md
```

## Forgejo API integration

### Endpoints used

```
# Get issue
GET  http://192.168.10.75:3000/api/v1/repos/{owner}/{repo}/issues/{num}

# List labels (idempotent label creation)
GET  /api/v1/repos/{owner}/{repo}/labels
POST /api/v1/repos/{owner}/{repo}/labels

# Apply / replace labels
POST   /api/v1/repos/{owner}/{repo}/issues/{num}/labels   # add
PUT    /api/v1/repos/{owner}/{repo}/issues/{num}/labels   # replace
DELETE /api/v1/repos/{owner}/{repo}/issues/{num}/labels/{label_id}

# Post comment
POST /api/v1/repos/{owner}/{repo}/issues/{num}/comments
```

### Auth

```bash
source ~/.env   # FORGEJO_TOKEN
curl -H "Authorization: token $FORGEJO_TOKEN" \
     -H "Content-Type: application/json" \
     "http://192.168.10.75:3000/api/v1/..."
```

### Rate limit guardrail

Batch mode caps at 60 req/min (Forgejo default). Pagination with `?limit=50&page=N`. On 429, exponential back-off (max 60s).

## Reuse / Synergy

- **`forgejo-pr`** — provides Forgejo API patterns + auth flow (reuse `read-config` + headers).
- **`feature-board`** — kanban view *across* features (this skill works at issue-level, complementary).
- **`forgejo-worktree`** — when triaging "in-progress", suggest worktree for the issue's branch.
- **`scope-check`** — invoked before transitioning to `done` if the linked PR touched files outside scope.

## Output Template (single-issue triage)

```markdown
## Triage : #{N} — {title}

**Current state**  : {old_state}
**Proposed state** : {new_state}
**Rationale**      : {1-2 sentences why}

**Heuristic hits** :
- {heuristic 1: pass/fail}
- {heuristic 2: pass/fail}
- LLM judge confidence : {0.0-1.0} (only if invoked)

**Transition validation** : {ALLOWED | FORBIDDEN — reason}

**Auto-comment preview** :
> Triaged → {new_state}. {rationale}
> — atlas triage @ {ts}

Apply? [y/N]
```

## Output Template (batch report)

```markdown
# Triage Report : {repo} — {YYYY-MM-DD}

## State distribution

| State          | Count | Δ vs 30d ago |
|----------------|-------|--------------|
| open           |   42  | +5           |
| needs-info     |   18  | -2           |
| blocked        |    7  | 0            |
| in-progress    |   12  | +3           |
| review         |    4  | +1           |
| done (closed)  |   89  | +24          |

## Stale issues (> 14d in current state)

- #103 needs-info — last activity 2026-04-02 (28d)
- #117 blocked — blocker #99 closed 2026-04-15, can transition

## Recommendations

- [ ] Auto-close 6 needs-info issues stale > 30d (no response)
- [ ] Re-triage 2 blocked issues whose blockers closed
- [ ] Surface 4 review issues to engineer-of-the-week
```

## Anti-patterns (avoid)

1. **Skipping the state machine** — never apply a state label without validating the transition.
2. **Silent label changes** — every transition MUST post the auto-comment.
3. **Re-opening `done` issues** — file a NEW issue with `relates-to:#N` instead.
4. **Batch --apply without --dry-run first** — always preview the diff.
5. **LLM-as-judge for everything** — heuristics catch 80% cheaper; reserve LLM for ambiguous tail.

## Pocock adaptation notes

The original mattpocock/skills/engineering/triage is a minimal one-screen skill (intentionally so). ATLAS adapts it with :

- **Explicit state machine** (Pocock leaves transitions implicit) — needed for Forgejo automation safety
- **Forgejo-specific labels + API integration** (Pocock is provider-agnostic)
- **CLI surface** (`atlas triage ...`) for batch mode and reporting
- **Heuristic ladder + LLM-as-judge fallback** — Pocock describes the "feel" of triage; ATLAS makes it executable
- **Synergy with `feature-board` + `forgejo-pr` + `forgejo-worktree`** — leverages existing ATLAS skills
- **Auto-comment template** — ensures audit trail for every transition (compliance need at G Mining)

Attribution preserved in frontmatter + `CREDITS.md`.

## See also

- `skills/forgejo-pr/SKILL.md` — PR lifecycle (issue → PR → merge)
- `skills/feature-board/SKILL.md` — feature-level dashboard (complementary scope)
- `skills/forgejo-worktree/SKILL.md` — worktree spawn for in-progress
- `.claude/references/forgejo-api.md` — Forgejo API reference
- CREDITS.md — Pocock attribution

---

## Practical workflow scenarios (re-merged from upstream 2026-05-03)

Per audit `memory/audit-mattpocock-drift-2026-05-03.md`, upstream's 8 practical workflow sections are now exposed via companion files. The atlas state-machine + heuristic ladder remains the canonical mechanism; the companions add the **practitioner playbook** for common scenarios.

### Scenarios covered by companion references

- **Invocation** — how to start a triage session (atlas: `atlas triage [--repo ...]`)
- **Resuming a previous session** — pick up where you left off without re-reading every issue
- **Triage a specific issue** — single-issue deep-dive flow (vs batch)
- **Show what needs attention** — surface issues by `needs-info`, `needs-triage`, `stalled`, `blocked` states
- **Quick state override** — when the heuristic gets it wrong, override with one command
- **Roles** — clarify who triages what (PM vs eng vs ops) when multiple humans collaborate
- **Reference docs** — links to project-specific labels, transition rules, exceptions
- **Needs-info template** — canonical comment template when reporter must clarify

### Companion references (ported 2026-05-03)

- [references/AGENT-BRIEF.md](references/AGENT-BRIEF.md) — briefing template for spawning a triage sub-agent (use with `atlas-team` or direct `Agent` tool)
- [references/OUT-OF-SCOPE.md](references/OUT-OF-SCOPE.md) — explicit out-of-scope rules: what is NOT triaged, what is NOT auto-transitioned, what requires HITL escalation