docs(issues): require release and duplicate checks (#2214)

Signed-off-by: Evan Lezar <elezar@nvidia.com>

Author: elezar

.agents/skills/create-github-issue/SKILL.md

@@ -17,16 +17,21 @@ This project uses YAML form issue templates. When creating issues, match the tem
 
 ### Bug Reports
 
-Do not add a type label automatically. The body must include an **Agent Diagnostic** section — this is required by the template and enforced by project convention. Apply area or topic labels only when they are clearly known.
+Do not add a type label automatically. The body must include an **Agent Diagnostic** section — this is required by the template and enforced by project convention. The diagnostic must identify the OpenShell version tested, whether the latest release or known fixes were checked, and whether possible duplicate issues were searched. If the agent cannot verify the latest release or search existing issues, say so explicitly instead of guessing. Apply area or topic labels only when they are clearly known.
 
 ```bash
 gh issue create \
   --title "bug: <concise description>" \
   --body "$(cat <<'EOF'
 ## Agent Diagnostic
 
-<Paste the output from the agent's investigation. What skills were loaded?
-What was found? What was tried?>
+- Skills loaded: <skills used during investigation>
+- OpenShell version tested: <version from openshell --version or other source>
+- Latest release checked: <version checked, or unable to verify>
+- Known fixes reviewed: <release notes / merged PRs checked, or unable to verify>
+- Possible duplicates reviewed: <existing issues searched, or unable to verify>
+- Findings: <what the agent found and tried>
+- Remaining reason for filing: <why this still appears to be a bug>
 
 ## Description
 
@@ -44,6 +49,8 @@ What was found? What was tried?>
 - OS: <os>
 - Docker: <version>
 - OpenShell: <version>
+- Latest release checked: <yes/no and reason>
+- Possible duplicates checked: <yes/no and reason>
 
 ## Logs
 

.agents/skills/triage-issue/SKILL.md

@@ -51,7 +51,7 @@ Query all open issues with the `state:triage-needed` label and process them in s
 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-6). Report a summary at the end listing each issue and its classification.
+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
 
@@ -89,7 +89,23 @@ Check whether the issue body contains a substantive agent diagnostic section. Lo
 
 **If the diagnostic section is substantive**, proceed to Step 4.
 
-## Step 4: Diagnose and Validate
+## 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:
 
@@ -114,20 +130,21 @@ Based on the sub-agent's analysis, also attempt to validate the report directly:
 - 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 5: Classify
+## Step 6: Classify
 
 Based on the investigation, classify the issue into one of these categories:
 
 | Classification | Criteria | Action |
 |---------------|----------|--------|
 | **bug-confirmed** | Agent diagnostic and codebase analysis confirm a real defect | Apply relevant `area:*` or `topic:*` labels as needed, remove `state:triage-needed`, and assign the built-in `Bug` issue type manually if needed |
 | **feature-valid** | Design proposal is sound, feasible given the architecture | Apply relevant `area:*` or `topic:*` labels as needed, remove `state:triage-needed`, and assign the built-in `Feature` issue type manually if needed |
+| **fixed-in-release** | Report targets an older OpenShell release and a newer release or merged PR appears to address the behavior; no fixed/current-release reproduction is provided | Comment with the fixing version and PR/issue when known. Close as completed when the fix is clear, or request a retest if confirmation is still needed. Remove `state:triage-needed` when closing |
 | **duplicate** | An existing open issue covers this | Link the duplicate, close with comment |
 | **user-error** | The reported behavior is expected, or the issue is a misconfiguration | Comment with explanation and guidance, close |
 | **needs-more-info** | Report is substantive but missing critical reproduction details | Comment requesting specifics, keep `state:triage-needed` |
 | **needs-investigation** | Report appears valid but requires deeper analysis (spike candidate) | Label `spike`, remove `state:triage-needed` |
 
-## Step 6: Post Triage Comment
+## Step 7: Post Triage Comment
 
 Post a structured comment with the triage marker:
 
@@ -136,7 +153,7 @@ Post a structured comment with the triage marker:
 >
 > ## Triage Assessment
 >
-> **Classification:** <classification from Step 5>
+> **Classification:** <classification from Step 6>
 >
 > ### Summary
 > <2-3 sentences: what was found, whether the report is valid>
@@ -148,7 +165,7 @@ Post a structured comment with the triage marker:
 > <Next steps: ready for spike, needs more info from reporter, can be closed, etc.>
 ```
 
-Apply the appropriate labels as determined in Step 5.
+Apply the appropriate labels as determined in Step 6.
 
 **Do not apply `state:agent-ready`.** That is always a human decision.
 

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -9,15 +9,20 @@ body:
 
         OpenShell is an agent-first project. Before filing this bug, point your coding agent at the repo and have it investigate using the available skills (`debug-openshell-cluster`, `debug-inference`, `openshell-cli`, etc.). See [CONTRIBUTING.md](https://github.com/NVIDIA/OpenShell/blob/main/CONTRIBUTING.md) for the full skills table.
 
+        Please also check the latest OpenShell release and search existing issues for possible duplicates before filing. If you cannot upgrade, retest, or search existing issues, explain why in the diagnostic.
+
   - type: textarea
     id: agent-diagnostic
     attributes:
       label: Agent Diagnostic
       description: |
-        Paste the output from your agent's investigation of this bug. What skills did it load? What did it find? What did it try?
+        Paste the output from your agent's investigation of this bug. What skills did it load? What did it find? What did it try? Which OpenShell version did it test, and did it check the latest release, known fixes, and possible duplicates?
       placeholder: |
         Example:
         - Loaded `debug-inference` skill
+        - Tested OpenShell v0.x.x
+        - Checked latest release / known fixes: no matching fix found
+        - Searched existing issues for duplicates: no matching issue found
         - Ran `openshell inference get` and `openshell provider get ollama`
         - Found `OPENAI_BASE_URL=http://127.0.0.1:11434/v1`, which is unreachable from the gateway
         - Updated the provider to use `host.openshell.internal`, but the issue persists because the gateway is remote
@@ -47,11 +52,13 @@ body:
     id: environment
     attributes:
       label: Environment
-      description: OS, Docker version, OpenShell version, and any other relevant details.
+      description: OS, Docker version, OpenShell version tested, whether the latest release and existing issues were checked, and any other relevant details.
       placeholder: |
         - OS: macOS 15.2 / Ubuntu 24.04 / Windows 11 + WSL2
         - Docker: Docker Desktop 4.x / Docker Engine 27.x
         - OpenShell: v0.x.x (output of `openshell --version`)
+        - Latest release checked: yes / no, because ...
+        - Possible duplicates checked: yes / no, because ...
     validations:
       required: true
 
@@ -75,5 +82,9 @@ body:
           required: true
         - label: I loaded relevant skills (e.g., `debug-openshell-cluster`, `debug-inference`, `openshell-cli`)
           required: true
+        - label: I checked the latest OpenShell release and either reproduced the issue there or explained why I cannot upgrade/test it
+          required: true
+        - label: I searched existing issues for possible duplicates or explained why I could not
+          required: true
         - label: My agent could not resolve this — the diagnostic above explains why
           required: true