triage

Files (3)

• AGENT-BRIEF.md
• OUT-OF-SCOPE.md
• SKILL.md

SKILL.md (first lines)

# Triage

Before reading relative links, run `cd '<loaded-skill-directory>' && pwd -P`
with this loaded file's directory to obtain the physical base, then resolve
links against that printed directory. Resolve the source symlink before applying
`..`. Read linked files even when their skills are absent from the discovery
list.

Move tracker items through the category and state roles below. When the
issue-tracker configuration treats external pull requests as a request surface,
apply the same process to them: a PR is an issue plus attached code. Resolve a
bare reference such as `#42` according to that configuration.

Prefix every issue body or comment posted during triage with:

```markdown
> _This was generated by AI during triage._
```

## Reference docs

- [AGENT-BRIEF.md](AGENT-BRIEF.md) — required structure for durable agent briefs
- [OUT-OF-SCOPE.md](OUT-OF-SCOPE.md) — rules for the `.out-of-scope/` knowledge
  base

## Roles and transitions

Assign exactly one category role:

- `bug` — existing behavior does not match its contract or expected behavior
- `enhancement` — requested behavior is new or changes an existing capability

Assign exactly one state role:

- `needs-triage` — maintainer evaluation is pending
- `needs-info` — information required from the reporter is pending
- `ready-for-agent` — validated implementation contract regardless of
  availability; execution still requires explicit authorization
- `ready-for-human` — implementation requires a human
- `wontfix` — the request will not be actioned

For a PR, evaluate the states against its attached code: `ready-for-agent` means
an agent brief identifies the next action on the diff; `ready-for-human` means a
human can merge it without another triage step.

These are canonical role names. Read their tracker-specific label mapping. If
the mapping is missing, follow [setup-omskills](../setup-omskills/SKILL.md) and
its scoped authorization gate before continuing, including in headless runs.
Respect read-only roles and return unresolved prerequisites to the responsible
caller. If an item has multiple category roles or multiple state roles, report
the conflict and obtain maintainer direction before any other triage action.

Normal transitions are:

- no state role → `needs-triage`;
- `needs-triage` → `needs-info`, `ready-for-agent`, `ready-for-human`, or
  `wontfix`; and
- `needs-info` → `needs-triage` after reporter activity.

A maintainer may override any transition. Explicit direction authorizes the
requested exceptional transition without another confirmation; state the
exception and exact changes before applying them. Ask only when the target state
or intended consequences remain materially ambiguous. The `ready-for-agent`
audit boundary below still applies.

## Invocation routing

Map natural-language requests to one of these branches:

- attention query, such as “Show me anything that needs my attention” →
  [Show items needing attention](#show-items-needing-attention);
- a specific item, such as “Let's look at #42” →
  [Triage a specific item](#triage-a-specific-item);
- an explicit state change, such as “Move #42 to ready-for-agent” →
  [Quick state override](#quick-state-override); or
- a ready-work query, such as “What's ready for agents to pick up?” → query the
  configured `ready-for-agent` role and report eligible items without selecting
  any into a Mission.

## Show items needing attention

Query the tracker and return three buckets, each ordered oldest first:

1. items with no state role, including items that already have a category role;
2. items with `needs-triage`; and
3. `needs-info` items with reporter activity newer than the latest triage notes.

When external PRs are configured as a request surface, include only external PRs
as defined by the tracker configuration and prefix each result with `[PR]` or
`[issue]`. This author filter applies only to discovery; always process an
explicitly named PR.

Show the count for each bucket and one line per item, then wait for the
maintainer to select an item.

## Triage a specific item

1. **Gather context.** Read the full body, comments, labels, author, and dates;
   for a PR, also read the complete diff. Extract conclusions and unanswered
   questions from prior triage notes. Inspect the affected code using the
   project's domain terms and applicable ADRs. Perform both checks:
   - **Redundancy:** search by domain concept, not only the reporter's wording,
     for an existing implementation of the requested behavior. Record the
     locations searched. If the behavior already exists, use the
     already-implemented `wontfix` outcome in step 5.
   - **Prior rejection:** read `.out-of-scope/*.md` and report entries that
     reject the same requested outcome or establish a scope boundary applicable
     to it. Use actor, domain concept, and constraints to determine whether the
     rejection applies.

2. **Verify.** Test the claim before recommending a state:
   - for a bug, follow the reporter's reproduction steps;
   - for an enhancement, confirm the current behavior or interface state that
     the request wants changed;
   - for a PR, check out the diff and run the commands or tests that exercise
     its stated behavior.

   Report one result: `confirmed`, with the exercised code path and observed
   result; `failed`, with the command or step that contradicted the claim; or

From luizomf/omskills, MIT.

More from luizomf/omskills