NVIDIA · krishicks · Aug 5, 2026
@@ -62,7 +62,7 @@ Fetch issue + comments
   ├─ Triage incomplete, awaiting information, or awaiting human disposition?
   │   → Report the blocking state and STOP
   │
-  ├─ state:accepted absent?
+  ├─ state:accepted and roadmap association both absent?
   │   → Human has not accepted the issue; STOP
   │
   ├─ No plan comment and no direct planning request and agent:plan-requested absent?
@@ -113,9 +113,9 @@ Stop before planning in any of these states:
 
 - `state:triage-needed`: the issue has not been assessed; use `triage-issue`.
 - `state:needs-info`: triage is waiting for evidence from the reporter.
-- `state:validated`: triage is complete, but a human has not yet decided whether OpenShell should invest in the work.
+- `state:validated` without roadmap placement: triage is complete, but a human has not yet decided whether OpenShell should invest in the work.
 
-Next, require `state:accepted`. It records the human decision to pursue the work. If no plan exists, require either a direct user request for planning or the human-applied `agent:plan-requested` label before generating one. Record any roadmap association as sequencing context, but do not require one. Never add or remove `state:accepted`, either human request label, or the `roadmap` label.
+Next, require a human acceptance signal: either `state:accepted` or placement on the roadmap. The label records acceptance without requiring scheduling; roadmap placement records acceptance and sequencing. If no plan exists, require either a direct user request for planning or the human-applied `agent:plan-requested` label before generating one. Never add or remove `state:accepted`, either human request label, or the `roadmap` label.
 
 ## Step 2: Fetch and Classify Comments
 
@@ -160,7 +160,7 @@ Task tool with subagent_type="principal-engineer-reviewer"
 
 In the prompt, instruct the reviewer to:
 
-1. Read the issue description thoroughly and identify what needs to change in the codebase.
+1. Read the issue's user story and identify what needs to change in the codebase. Treat reporter diagnostics or solution ideas as optional context, not as authoritative or current analysis.
 2. Map the requirements to existing code — read the relevant source files.
 3. Determine the **issue type** — one of: `feat` (new feature), `fix` (bug fix), `refactor`, `chore`, `perf`, `docs`.
 4. Propose the minimal set of changes that satisfies the requirements.
@@ -174,6 +174,8 @@ In the prompt, instruct the reviewer to:
 9. Assess **gateway config documentation impact** — if the change adds, removes, renames, or changes defaults for gateway TOML keys or driver-specific config options, the plan must include an update to `docs/reference/gateway-config.mdx`. If the change is surfaced through Helm or a compute-driver overview, also include `docs/reference/sandbox-compute-drivers.mdx` or the relevant deployment docs.
 10. Assess **LSM compatibility** — if the change touches process identity, `/proc` filesystem access, binary execution, or inter-process visibility, flag whether it will behave differently on hosts running SELinux (enforcing) or AppArmor. In particular, tests that fork+exec into system binaries will fail on SELinux-enforcing hosts due to cross-label `/proc/<pid>/exe` access restrictions.
 
+Perform this investigation against the current branch and current product behavior. If the issue contains earlier diagnostics, verify them rather than relying on them.
+
 ### A2: Post the Plan Comment
 
 Post the plan as a comment on the issue. This is the **canonical plan comment** that will be edited in place as the plan evolves.

@@ -17,74 +17,73 @@ 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. 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.
+Do not add a type label automatically. Write the issue as a user story. Capture the affected persona, desired user-facing workflow or capability, reason and current impact, the workflow that exposes the problem, and the relevant environment. Do not require a diagnosis, internal implementation design, or agent output. Apply area or topic labels only when they are clearly known.
 
 ```bash
 gh issue create \
   --title "bug: <concise description>" \
   --body "$(cat <<'EOF'
-## Agent Diagnostic
+## What persona does this impact?
 
-- 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>
+<The affected role in the workflow, such as an operator, sandbox creator, or agent>
 
-## Description
+## What does this persona need to be able to do?
+
+<The user-facing workflow, capability, or outcome the persona needs>
 
-**Actual behavior:** <what happened>
+## Why does this matter to the persona?
 
-**Expected behavior:** <what should happen>
+<What happens today and how it affects the persona's work>
 
-## Reproduction Steps
+## What workflow exposes the problem?
 
 1. <step>
 2. <step>
 
 ## Environment
 
 - OS: <os>
-- Docker: <version>
 - OpenShell: <version>
-- Latest release checked: <yes/no and reason>
-- Possible duplicates checked: <yes/no and reason>
+- Platform, deployment, runtime, or integration: <relevant details>
 
-## Logs
+## Relevant Logs
 
 ```
-<relevant output>
+<optional minimal, redacted output>
 ```
 EOF
 )"
 ```
 
 ### Feature Requests
 
-Do not add a type label automatically. The body must include a **Proposed Design** — not a "please build this" request. Apply area or topic labels only when they are clearly known.
+Do not add a type label automatically. Use the same core user-story structure as a bug report. Ask for the desired user-facing workflow, but do not require the reporter to decide whether the gap is a defect or missing capability, design the internal implementation, or include agent output. Apply area or topic labels only when they are clearly known.
 
 ```bash
 gh issue create \
   --title "feat: <concise description>" \
   --body "$(cat <<'EOF'
-## Problem Statement
+## What persona does this impact?
+
+<The affected role in the workflow, such as an operator, sandbox creator, or agent>
+
+## What does this persona need to be able to do?
 
-<What problem does this solve? Why does it matter?>
+<The user-facing workflow, capability, or outcome the persona needs>
 
-## Proposed Design
+## Why does this matter to the persona?
 
-<How should this work? Describe the system behavior, components involved,
-and user-facing interface.>
+<What happens today and how it affects the persona's work>
 
-## Alternatives Considered
+## What workflow exposes the need?
 
-<What other approaches were evaluated? Why is this design better?>
+1. <step>
+2. <step>
 
-## Agent Investigation
+## Environment
 
-<If the agent explored the codebase to assess feasibility, paste findings here.>
+- OpenShell: <version>
+- Platform, deployment, runtime, or integration: <relevant details>
 EOF
 )"
 ```
@@ -114,7 +113,7 @@ EOF
 
 GitHub built-in issue types (`Bug`, `Feature`, `Task`) should come from the matching issue template when possible, or be set manually afterward. Do not try to emulate them through labels.
 
-Creating an issue does not accept it for roadmap work or queue agent work. Agents never apply the `roadmap` label, add issues to the roadmap project, or apply `agent:plan-requested` or `agent:implementation-requested`. Community issues proceed through `triage-issue`; a human decides whether technically validated work should be accepted and places it on the roadmap. The request labels queue work for unattended agents; a user may instead direct an agent to a specific issue.
+Creating an issue does not accept it or queue agent work. Agents never apply `state:accepted`, the `roadmap` label, add issues to the roadmap project, or apply `agent:plan-requested` or `agent:implementation-requested`. Community issues proceed through `triage-issue`; a human accepts technically validated work with `state:accepted` or roadmap placement. The request labels queue work for unattended agents; a user may instead direct an agent to a specific issue.
 
 ## Useful Options
 

@@ -211,7 +211,7 @@ gh issue create \
 - <what tests exist for the affected area today, what patterns should be followed, any test infrastructure gaps>
 
 ---
-*Created by spike investigation. `state:validated` means the issue is ready for human disposition; `state:needs-info` means specific evidence is still required. A human applies `state:accepted` if OpenShell should pursue the work and places it on the roadmap separately. To queue unattended agent planning, a human applies `agent:plan-requested`; a direct request to an agent does not require that label.*
+*Created by spike investigation. `state:validated` means the issue is ready for human disposition; `state:needs-info` means specific evidence is still required. A human applies `state:accepted` or places the issue on the roadmap if OpenShell should pursue the work. To queue unattended agent planning, a human applies `agent:plan-requested`; a direct request to an agent does not require that label.*
 EOF
 )"
 ```
@@ -235,7 +235,7 @@ After creating the issue, report:
 
 For `state:validated`:
 
-> Review the issue and decide whether OpenShell should pursue it. If yes, replace `state:validated` with `state:accepted` and separately associate it with a roadmap item. The work may remain human-owned. Apply `agent:plan-requested` to queue planning for an unattended agent, or directly ask an agent to use `build-from-issue`. If no, close it as not planned and record the rationale.
+> Review the issue and decide whether OpenShell should pursue it. If yes, apply `state:accepted`, associate it with a roadmap item, or do both. Either action records acceptance; roadmap placement additionally records sequencing. The work may remain human-owned. Apply `agent:plan-requested` to queue planning for an unattended agent, or directly ask an agent to use `build-from-issue`. If no, close it as not planned and record the rationale.
 
 For `state:needs-info`:
 

@@ -119,8 +119,8 @@ For each file in the table above, check for the following inconsistencies:
 
 ### Issue Templates
 
-1. **`bug_report.yml`** — Skill names in the Agent Diagnostic guidance and checklist must exist.
-2. **`feature_request.yml`** — Skill names in the Agent Investigation guidance must exist.
+1. **`bug_report.yml`** — Must collect the affected persona, desired user-facing workflow or capability, impact, workflow or reproduction, and environment. Logs may be bug-specific, but reporter diagnostics must not be required.
+2. **`feature_request.yml`** — Must collect the same core user-story and environment fields as the bug report without requiring an internal implementation design or reporter diagnostics.
 3. **`config.yml`** — Skill category descriptions in contact links should be accurate.
 
 ### Issue Triage Workflow

@@ -25,7 +25,7 @@ Triage establishes technical validity; it does not decide whether valid work bel
 
 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.
+`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 applying `state:accepted`, placing the issue on the roadmap, or doing both 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.
 
@@ -98,18 +98,14 @@ 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 a human already declined the issue, applied `state:accepted`, or placed it on the roadmap**, do not undo or reinterpret that decision.
 - **If the marker is not found**, proceed to Step 3.
 
-## Step 3: Validate the Agent-First Gate
+## Step 3: Check Report Completeness
 
-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:
+Read the issue as a user story. Identify the affected persona, desired user-facing workflow or capability, reason and current impact, workflow or reproduction, and relevant environment. Reporter-supplied diagnostics, internal implementation designs, and agent output are optional and must not be used as an intake gate.
 
-- 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 the report contains enough context to understand and assess the user need, continue. If a material part of the story, workflow, or environment is missing, classify it as `needs-information`, request only the exact missing information, 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.
@@ -121,7 +117,7 @@ Proceed to Step 4 for reports requiring technical validation.
 
 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.
+1. Extract the reported OpenShell version from the issue body, 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>`
@@ -140,12 +136,11 @@ Assess the report by investigating the codebase. Use the `principal-engineer-rev
 ```
 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?
+  1. What persona, desired capability, and impact does the user story establish?
+  2. Can the described workflow be reproduced or otherwise validated from the information given?
+  3. Does the current product support the requested outcome, and what component owns the behavior?
+  4. Is the report best classified as a bug, feature request, support request, or another category?
   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?
@@ -205,14 +200,14 @@ Post a structured comment with the triage marker:
 > - **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.
+> Decide whether OpenShell should address this issue. If yes, apply
+> `state:accepted`, associate it with a roadmap item, or do both, and decide
+> whether the work remains human-owned. Either action records acceptance;
+> roadmap placement additionally records sequencing.
 > 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.
@@ -230,7 +225,7 @@ Community issue filed
         |
   state:validated
         |
-  human decline OR state:accepted + roadmap placement
+  human decline OR state:accepted / roadmap placement
         |
   create-spike          (if deeper investigation is approved)
         |