Triage Issue

Triage Issue

Establish the facts a human needs to decide whether OpenShell should address an issue and, if so, where it belongs on the roadmap. Triage does not authorize work, sequence it, or produce an implementation plan.

Prerequisites

• The gh CLI must be authenticated (gh auth status)
• You must be in a git repository with a GitHub remote
• The workflow labels state:validated, state:accepted, and state:needs-info must exist. Report missing labels to the operator; do not create them implicitly.

Critical: Disposition and Roadmap Placement Are Human-Only

Triage establishes technical validity; it does not decide whether valid work belongs on the roadmap. Agents must never:

• Decide that OpenShell should or should not invest in otherwise valid work.
• Apply or remove state:accepted.
• Add an issue to the roadmap project, apply or remove the roadmap label, or recommend a specific roadmap item.
• Apply agent:plan-requested or agent:implementation-requested.
• Treat technical validity as product acceptance.

OpenShell has no priority:* labels. Sequencing comes from association with an item on the OpenShell Roadmap, and that association is a maintainer decision.

state:validated means the factual assessment is complete and awaits human disposition. A human declines by closing the issue as not planned with a rationale, or accepts by replacing state:validated with state:accepted and placing the issue on the roadmap as documented in CONTRIBUTING.md. Accepted work may remain human-owned. A maintainer can queue deeper agent investigation or planning with agent:plan-requested, or directly ask an agent to work on a specific issue.

The optional agent:* workflow controls unattended queue pickup: agent:plan-requested queues planning, and agent:implementation-requested queues implementation after plan review. A direct user instruction separately authorizes the phase it requests and does not require either label.

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

Batch mode requires a confirmation gate before processing. This prevents accidental mass-commenting on a public repository.

Step 1: Preview. Query all matching issues and display a summary:

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

Present the results to the user:

Found N issues with state:triage-needed:

  #250  Bug: sandbox fails to start with VM driver
  #312  Feature: add --output yaml to sandbox list
  ... (show up to 10, then "and N more")

This will post a triage comment on each issue.

Step 2: Confirm. Ask the user for explicit confirmation before proceeding. Use AskUserQuestion with options "Proceed with all N issues", "Let me pick specific issues", and let them provide custom input. Do not proceed without confirmation.

Step 3: Process. Only after confirmation, run the full triage workflow (Steps 1-7 below) for each issue. 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 a human already declined the issue or applied state:accepted, do not undo or reinterpret that decision.
• 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. Treat this as evidence quality, not as a reason to skip obvious safety or routing actions. 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 is missing, continue when the report already contains enough concrete evidence to assess safely. Otherwise classify it as needs-information, request the exact missing evidence, remove state:triage-needed, and add state:needs-info.

• If a public issue may disclose a security vulnerability, do not repeat or expand sensitive details. Classify it as security-report and direct the operator to SECURITY.md.
• Route usage questions and support requests to the documented support venue.
• Handle clear duplicates, wrong-repository reports, and objectively expected behavior without requiring a full technical investigation.

Proceed to Step 4 for reports requiring technical validation.

Step 4: Check Reported Version and Known Fixes

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

• 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.
• Check current release information and known fixes when available:
• gh release list --limit 10
• gh release view <tag>
• linked issues, merged PRs, release notes, local git tags/history, and both open and closed possible duplicates
• 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, identify a concrete fixing change before using fixed-in-release. If the causal link is uncertain, request a retest instead of declaring the issue fixed.

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, is it technically coherent and feasible? Do not decide whether the project should accept it.
  6. Are there any open or closed issues that duplicate this?
  7. What uncertainty remains, and what exact evidence would resolve it?

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

Record impact signals for the human decision: affected users and scope, regression status, workaround availability, severity evidence, and evidence quality. Do not convert those facts into a roadmap or sequencing recommendation.

Step 6: Classify

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

| Classification | Meaning | Agent action |

|---|---|---|

| validated-bug | Evidence confirms a real defect | Add relevant area/topic labels; replace triage/needs-info state with state:validated; leave open |

| validated-feature | The proposal is technically coherent and feasible | Add relevant area/topic labels; replace triage/needs-info state with state:validated; leave open |

| needs-investigation | The report is credible but needs a deeper spike | Add spike if available; replace triage/needs-info state with state:validated; leave open for a human decision on whether to invest in the spike |

| needs-information | Critical reproduction or environment evidence is missing | Replace state:triage-needed with state:needs-info; request the exact missing evidence |

| cannot-reproduce | A faithful attempt did not reproduce, but the report may still be valid | Replace state:triage-needed with state:needs-info; document the attempt and request discriminating evidence |

| fixed-in-release | A concrete released change fixes the reported behavior | Explain the fix and version; close only when the causal link is clear, otherwise request a retest |

| duplicate | Another open or closed issue is the canonical report | Link the canonical issue and close |

| expected-behavior | Code and documentation establish that the behavior is intentional | Explain the behavior and close |

| support-request | The report asks for usage help rather than tracking work | Provide the support route and close |

| wrong-repository | Another repository owns the affected component | Link the correct tracker and close |

| security-report | The report may contain a vulnerability | Avoid further public analysis and direct the operator to SECURITY.md for safe handling |

Do not use validated-feature to imply roadmap acceptance. Do not use expected-behavior to decline a technically valid feature request.

Step 7: Post Triage Comment

Post a structured comment with the triage marker:

> **📋 triage-agent**
>
> ## Triage Assessment
>
> **Classification:** <validated-bug | validated-feature | needs-investigation>
>
> ### Summary
> <What was established and confidence in the evidence.>
>
> ### Investigation
> <Reproduction results, code/release evidence, affected components, and duplicates.>
>
> ### Impact Signals
> - **Affected users/scope:** <facts or unknown>
> - **Regression:** <yes/no/unknown>
> - **Workaround:** <available/unavailable/unknown>
> - **Evidence quality:** <high/medium/low with reason>
>
> ### Human Decision Required
> Decide whether OpenShell should address this issue. If yes, replace
> `state:validated` with `state:accepted`, associate it with a roadmap
> item, and decide whether the work remains human-owned.
> To queue investigation or planning for an unattended agent, also apply
> `agent:plan-requested`. You can instead directly ask an agent to use
> `create-spike` or `build-from-issue` on this issue. If no, close it as not
> planned and record the rationale.
> Roadmap association is independent sequencing metadata.

For other outcomes, replace the impact and decision sections with the exact information request, objective resolution, or safe routing guidance.

Keep exactly one intake/triage state among state:triage-needed, state:needs-info, and state:validated. Remove state:triage-needed after every completed assessment. Never apply state:accepted, any agent:* label, or the roadmap label during triage. Never close a validated issue.

Relationship to Other Skills

Community issue filed
        |
  [GitHub Action: instant gate check]
        |
  triage-issue
        |
  state:validated
        |
  human decline OR state:accepted + roadmap placement
        |
  create-spike          (if deeper investigation is approved)
        |
  human queues planning with agent:plan-requested
  OR directly requests planning
        |
  build-from-issue      (creates implementation plan)
        |
  human queues implementation with agent:implementation-requested
  OR directly requests implementation
        |
  implementation

• triage-issue establishes technical validity and impact evidence.
• Humans decide whether to accept valid work and where it lands on the roadmap.
• create-spike deepens investigation only after that investment is approved.
• build-from-issue may be invoked directly for a specific issue. Unattended agents use agent:plan-requested to pick up planning and agent:implementation-requested to pick up implementation.

Triage is the assessment layer. It does not sequence work, accept it onto the roadmap, plan, or build.