triage-issue

Triage Issue

Assess, classify, and route community-filed issues. This is the front door for community inflow — distinct from build-from-issue, which is the maintainer execution tool for implementation.

Prerequisites

• The gh CLI must be authenticated (gh auth status)
• You must be in a git repository with a GitHub remote

Critical: state:agent-ready Label Is Human-Only

The state:agent-ready label is a human gate. Triage never applies this label. Triage assesses and classifies — humans decide what gets built. This is a non-negotiable safety control.

Agent Comment Marker

All comments posted by this skill must begin with the following marker line:

> **📋 triage-agent**

This marker distinguishes triage comments from human comments and from other skills (🏗️ build-from-issue-agent, 🔒 security-review-agent, etc.).

Invocation Modes

This skill supports two modes:

Single Issue

triage issue 250
triage issue #250

Assess one specific issue. Proceed to Step 1 with the given issue number.

Batch

triage issues

Query all open issues with the state:triage-needed label and process them in sequence:

gh issue list --label "state:triage-needed" --state open --json number,title --jq '.[].number'

For each issue returned, run the full triage workflow (Steps 1-7). Report a summary at the end listing each issue and its classification.

Step 1: Fetch the Issue

Strip any leading # from the issue number and fetch the issue.

gh issue view <id> --json title,body,state,labels,author,comments

If the issue is closed, report that and stop.

Step 2: Check for Prior Triage

Search the issue comments for the triage agent marker (> **📋 triage-agent**).

• If the marker is found and no subsequent human comments exist with new information or questions, report that the issue has already been triaged and stop.
• If the marker is found but there are newer human comments with additional information, proceed to Step 3 to re-evaluate with the new context.
• If the marker is not found, proceed to Step 3.

Step 3: Validate the Agent-First Gate

Check whether the issue body contains a substantive agent diagnostic section. Look for:

• An "Agent Diagnostic" heading or section (from the bug report template)
• Evidence that the reporter used agent skills (skill names mentioned, diagnostic output pasted)
• Concrete investigation output (not just placeholder text or "N/A")

If the diagnostic section is missing or clearly placeholder:

1. Add the state:triage-needed label if not already present:

   gh issue edit <id> --add-label "state:triage-needed"
   

2. Do not post a standalone redirect comment. Report the missing diagnostic to the operator and stop unless a human explicitly asks you to continue triage anyway.

If the diagnostic section is substantive, proceed to Step 4.

Step 4: Check Reported Version and Known Fixes

Before deeper diagnosis, determine whether the report may already be fixed in a newer release.

1. Extract the reported OpenShell version from the issue body, Agent Diagnostic, environment section, logs, and comments. If no version is provided, record that as missing context and continue.
2. Check current release information and known fixes when available:
   • gh release list --limit 10
   • gh release view <tag>
   • linked issues, merged PRs, release notes, and local git tags/history
3. If network access or release metadata is unavailable, state the limitation in the triage comment instead of guessing.

If the issue targets an older OpenShell release and a newer release or merged PR appears to address the same behavior:

• If the reporter has already reproduced the issue on the fixed/current release, continue to Step 5.
• If the reporter has not tested the fixed/current release, use the fixed-in-release classification in Step 6. Reference the fixing version and PR/issue when known, and ask for a fresh report or reopen if the issue still reproduces on that version.

Step 5: Diagnose and Validate

Assess the report by investigating the codebase. Use the principal-engineer-reviewer sub-agent via the Task tool:

Prompt the sub-agent with:
- The full issue title and body
- The reporter's agent diagnostic output
- Instructions to evaluate with a skeptical lens:
  1. Is this report describing a real problem or user error?
  2. Can the described behavior be reproduced from the information given?
  3. Does the reporter's agent diagnostic match what you see in the codebase?
  4. If this is a bug, what component is affected?
  5. If this is a feature request, does the design make sense given the architecture?
  6. Are there any existing issues that duplicate this?

Based on the sub-agent's analysis, also attempt to validate the report directly:

• For bug reports: check the relevant code paths, look for the described failure mode
• For feature requests: assess feasibility against the existing architecture
• For gateway deployment or infrastructure issues: reference the debug-openshell-cluster skill's known failure patterns
• For inference and provider-topology issues: reference the debug-inference skill's known failure patterns
• For CLI/usage issues: reference the openshell-cli skill's command reference

Step 6: Classify

Based on the investigation, classify the issue into one of these categories:

Step 7: Post Triage Comment

Post a structured comment with the triage marker:

> **📋 triage-agent**
>
> ## Triage Assessment
>
> **Classification:** <classification from Step 6>
>
> ### Summary
> <2-3 sentences: what was found, whether the report is valid>
>
> ### Investigation
> <Key findings from the codebase analysis. Reference specific files and components.>
>
> ### Recommendation
> <Next steps: ready for spike, needs more info from reporter, can be closed, etc.>

Apply the appropriate labels as determined in Step 6.

Do not apply state:agent-ready. That is always a human decision.

Relationship to Other Skills

Community issue filed
        |
  [GitHub Action: instant gate check]
        |
  triage-issue          ← this skill
        |
  create-spike          (if classification is needs-investigation)
        |
  build-from-issue      (if human applies state:agent-ready)

• triage-issue decides whether an issue is valid and how to classify it.
• create-spike does deep feasibility investigation for issues that need it.
• build-from-issue implements once a human approves.

Triage is the assessment layer. It does not plan or build — it evaluates and routes.