triage

Files (1)

• SKILL.md

SKILL.md (first lines)

# Triage

Sort a **seed** of reports into Specs and parked Issues. One distinct problem → one Issue. Apply each result in this run; the closing **summary** is the review.

## Seed

The seed is what the maintainer handed this session: a pasted email, a markdown file, a description, ticket text, a reference to an Issue, or a query such as "every `needs-triage` Issue".

Issues live in the repo's **Tracker**: carry out each operation on one — file, read, list, rewrite, set status, comment, attach, link, close — as `.agents/refs/tracker.md` says, or as [setup/LOCAL.md](../setup/LOCAL.md) says when the repo has no ref.

1. If the invocation has no seed, ask for one. Stop until it arrives.
2. A reference to an Issue in this Tracker is the Issue this problem updates. A query lists the Tracker by status; each Issue it returns is the Issue its problem updates.
3. Anything else — a paste, a file, an issue from another system — is seed text: new work. What this run files goes to this repo's Tracker. Leave every Issue the seed does not name as it is.

Done: the seed text is in context.

## Split

Two findings are **distinct** when one can be resolved without the other. A list of items is the starting set. Split an item that contains more than one distinct problem. Queue extras found while investigating into this same run.

Done: every distinct problem is named. More may join during investigate; each joins this list.

## Per problem

For each distinct problem, gather → verify → apply. When the seed is an existing Issue being split, file each extra first as a new Issue whose body is only the extracted problem; the original Issue keeps the first problem and takes its ending.

### Gather

Read the seed text for this problem. If this updates an existing Issue, read it with its comments and ask only what is still open. Explore the codebase using the project's domain glossary, respecting ADRs in the area.

Search for an existing implementation of the requested behaviour by domain concept (not just the request's wording). Record where you looked. Found → skip verify, apply **not filed**.

For a bug, search the Tracker and the git log for earlier fixes of the same problem. Two or more that failed → [Attack the premise](../to-spec/PRINCIPLES.md#attack-the-premise) before choosing a fix. When an earlier fix exists, or the bug sits in code that looks deliberate, such as a guard, a limit, or a workaround, run the `/why` skill on that code before choosing a fix, and carry its Preserve, Change, Avoid, and Risk lists into the Spec.

Done: the problem is already implemented, or you have enough of the code to verify and classify.

### Verify

For a bug, reproduce it from the reporter's steps. Outcome: confirmed (with code path), failed, or insufficient detail (`needs-info`). A confirmed reproduction goes into the Spec as the test that fails on today's code. A report that claims a number — slower, bigger, costlier — is confirmed by measuring it, per [Explain the number](../to-spec/PRINCIPLES.md#explain-the-number).

Done: a verify outcome is recorded.

### Apply

Trust an explicit override in the seed (`spec this`, `ready-for-agent`, or `ready-for-human` → Spec; `needs-info`, `needs-human`, `needs-grilling` → that park). Pick exactly one ending and apply it. Every Issue this run leaves open carries a category, `bug` or `enhancement`.

**Spec** — Buildable. Read [`to-spec/SKILL.md`](../to-spec/SKILL.md) and follow it — `/to-spec` does not load as a skill — scoped to this problem alone, naming this problem's Issue when it has one: `/to-spec` rewrites that Issue into the Spec, or files one. Work the maintainer or another person will build is `ready-for-human`; tell `/to-spec` so. All other Specs are `ready-for-agent`.

A **park** files this problem's Issue, or updates the one it has: set its status to the park's name and add the park's comment.

**needs-info** — not enough information. Park. The comment:

```markdown
**What we've established so far:**

- point 1

**What we still need from you (@reporter):**

- question 1
```

Questions are specific and actionable.

**needs-human** — waiting on a secret or a manual test only a person can supply. Park. Short comment: why this status, what is known, what is blocked.

**needs-grilling** — a human must decide the solution in a later `/grill-with-docs` session. Park. Short comment: why this status, what is known, what is blocked.

**Not filed** — rejected or already implemented. When this problem has an Issue, close it as not planned, with a comment saying why. Otherwise mention it only in the summary.

**Attach** — when this problem's seed text references images, such as `![alt](/path/shot.png)`, attach them to its Issue once its ending has filed or updated it: after `/to-spec` returns on the Spec ending, after the park's comment on a park. A problem that is not filed attaches nothing. When the Tracker ref gives no Attach, or says it is unavailable, or an upload fails, comment the image paths instead and name each file in the summary for the user to add.

Every comment starts with:

```
> *This was generated by AI during triage.*
```

Before any comment a reporter will read, read [`technical-writing/SKILL.md`](../technical-writing/SKILL.md) and follow it — `/technical-writing` does not load as a skill.

A comment or body the Tracker takes from a file goes in a folder made once with `mktemp -d`, which the run deletes at its end. A path built from an Issue's number is shared: another triage session on the same Issue, such as a shared parent, writes it too, and a failed command then posts that session's draft.

Done: every named problem has exactly one ending applied in the Tracker, or is not filed, every filed problem's images are attached or named for the user, and extras found during investigate have been named and run through this section.

## Summary

End with a summary the people in the session can follow up from. For every problem: what it was, and either its Issue's reference and status, or that it was not filed, why, and the reference of any Issue it closed. Name every image left for the user to attach, with its path and its Issue. The summary is the review.

Done: the summary lists every problem this run handled. Then read [`retro/SKILL.md`](../retro/SKILL.md) and follow it — `/retro` does not load as a skill.

From michielvandermeer/skills, MIT.

More from michielvandermeer/skills