From c95ae47e98e797129c6751d82a1e719b668e61c3 Mon Sep 17 00:00:00 2001 From: Evan Lezar Date: Fri, 10 Jul 2026 17:42:13 +0200 Subject: [PATCH] docs(issues): require release and duplicate checks Signed-off-by: Evan Lezar --- .agents/skills/create-github-issue/SKILL.md | 13 ++++++--- .agents/skills/triage-issue/SKILL.md | 29 ++++++++++++++++----- .github/ISSUE_TEMPLATE/bug_report.yml | 15 +++++++++-- 3 files changed, 46 insertions(+), 11 deletions(-) diff --git a/.agents/skills/create-github-issue/SKILL.md b/.agents/skills/create-github-issue/SKILL.md index b1311a297e..d196fc8c8d 100644 --- a/.agents/skills/create-github-issue/SKILL.md +++ b/.agents/skills/create-github-issue/SKILL.md @@ -17,7 +17,7 @@ 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 \ @@ -25,8 +25,13 @@ gh issue create \ --body "$(cat <<'EOF' ## Agent Diagnostic - +- Skills loaded: +- OpenShell version tested: +- Latest release checked: +- Known fixes reviewed: +- Possible duplicates reviewed: +- Findings: +- Remaining reason for filing: ## Description @@ -44,6 +49,8 @@ What was found? What was tried?> - OS: - Docker: - OpenShell: +- Latest release checked: +- Possible duplicates checked: ## Logs diff --git a/.agents/skills/triage-issue/SKILL.md b/.agents/skills/triage-issue/SKILL.md index 54e726a5d9..8d602a9023 100644 --- a/.agents/skills/triage-issue/SKILL.md +++ b/.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 ` + - 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,7 +130,7 @@ 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: @@ -122,12 +138,13 @@ Based on the investigation, classify the issue into one of these categories: |---------------|----------|--------| | **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:** > > ### Summary > <2-3 sentences: what was found, whether the report is valid> @@ -148,7 +165,7 @@ Post a structured comment with the triage marker: > ``` -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. diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 74fa4bf5d4..de5d8112ae 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.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