agentation-triage

---
name: agentation-triage
description: Batch triage and prioritization of Agentation annotations. Fetches all pending annotations across sessions, groups by page/severity/component, creates a prioritized plan, and optionally dispatches parallel agents to resolve them. Use when the user says "triage annotations," "process all feedback," "prioritize annotations," or when there's a backlog of unprocessed annotations.
---

# Agentation Triage

Batch-process all pending Agentation annotations: fetch, categorize, prioritize, plan, and optionally dispatch parallel agents to resolve them.

## When to Use

- Multiple annotations have accumulated across pages
- User wants a summary of all outstanding feedback before acting
- User wants to dispatch agents to fix everything in parallel
- End-of-session cleanup of accumulated feedback

## Step 1: Fetch All Pending

```
Call agentation_get_all_pending
```

If count is 0, report "No pending annotations" and exit.

## Step 2: Categorize

Group annotations into buckets:

### By Severity
| Severity | Priority | Action |
|----------|----------|--------|
| `blocking` | P0 — Fix immediately | These block the user from working |
| `important` | P1 — Fix in this session | Significant issues that affect quality |
| `suggestion` | P2 — Fix if time permits | Nice-to-haves and polish |

### By Intent
| Intent | Handling |
|--------|----------|
| `fix` | Bug fix — locate and patch |
| `change` | Enhancement — implement the requested change |
| `question` | Reply with answer via `agentation_reply` |
| `approve` | Positive feedback — resolve with acknowledgment |

### By Kind (v3.0+)
| Kind | Handling |
|------|----------|
| `feedback` | Standard annotation — fix/change/question |
| `placement` | Layout mode — user wants a component added (delegate to agentation-layout) |
| `rearrange` | Layout mode — user wants elements reordered (delegate to agentation-layout) |

### By Page (URL)
Group annotations that target the same page. Annotations on the same page often relate to each other and should be fixed together to avoid conflicting edits.

### By Component
If multiple annotations target the same React component (from `reactComponents` field), group them. A single edit pass is more efficient than multiple.

## Step 3: Present the Plan

Output a triage report in this format:

```markdown
## Annotation Triage Report

**Total pending:** {count}
**Sessions:** {number of unique sessions}

### P0 — Blocking ({count})
- [{annotationId}] {page} — {comment preview} (component: {reactComponents})

### P1 — Important ({count})
- [{annotationId}] {page} — {comment preview} (component: {reactComponents})

### P2 — Suggestions ({count})
- [{annotationId}] {page} — {comment preview} (component: {reactComponents})

### Questions ({count})
- [{annotationId}] {page} — {comment preview}

### Approvals ({count})
- [{annotationId}] {page} — {comment preview}

### Recommended approach:
- {n} annotations can be resolved by editing {component} in {file}
- {n} annotations are on page {url} — fix together
- {n} questions need replies
- {n} approvals to acknowledge
```

## Step 4: Execute (User Choice)

Ask the user how they want to proceed:

### Option A: Fix All Sequentially
Process annotations in priority order (P0 first) using the agentation-watch pattern:
acknowledge → locate code → fix → resolve

### Option B: Dispatch Parallel Agents
For large backlogs, dispatch agents grouped by page or component:

```
For each page group:
  Launch Agent with prompt:
    "Fix these Agentation annotations on {page}:
     {list of annotation IDs, comments, and element paths}

     After fixing each one, call agentation_resolve(annotationId, summary).
     Follow the design system rules in CLAUDE.md."
```

Guidelines for parallel dispatch:
- Group by page (annotations on the same page go to the same agent)
- Max 3-4 concurrent agents to avoid conflicts
- Each agent gets the full annotation context (comment, element, component, severity)
- Questions and approvals can be handled in the main thread (no code changes needed)

### Option C: Fix P0/P1 Only
Skip suggestions, handle only blocking and important annotations.

### Option D: Review Only
Just present the report, don't fix anything. User will decide later.

## Step 5: Cleanup

After all annotations are processed:
1. Call `agentation_get_all_pending` to verify count is 0
2. Report summary: "{n} resolved, {n} dismissed, {n} replied to"
3. If any remain, list them with reasons (couldn't find code, ambiguous request, etc.)

## Handling Stale Annotations

Annotations older than 24 hours may reference code that has since changed. For stale annotations:
1. Check if the referenced component/element still exists
2. If the issue was already fixed (e.g., by a different commit), dismiss with reason
3. If the code has changed significantly, reply asking if the feedback still applies

## Integration with Initiative Cards

This project has a webhook at `/api/agentation/route.ts` that saves annotations as initiative cards in Supabase. When triaging:
- Check if the annotation already exists as an initiative card (match by `external_id`)
- Update the card status when resolving/dismissing annotations
- This keeps the Command Center board in sync with annotation status