---
name: create-issue
description: Create a GitHub issue following the project's issue templates. Classifies the issue type, fills required fields per template, and creates it via gh CLI. Use when the user wants to file a bug, request a feature, or create any GitHub issue.
---

# Create GitHub Issue

Create issues that follow `.github/ISSUE_TEMPLATE/` templates exactly.

## Step 0: Determine Input Source

Check how the issue was triggered:

**A) From `KNOWN_ISSUES.md`** — If user says "create issue from known issues", "/create-issue known", or similar:

1. Read `KNOWN_ISSUES.md` from project root
2. If file doesn't exist or has no entries, tell user "No known issues found" and **stop**
3. List all entries with their title, severity, and brief description
4. Present the list and ask the user which issue they want to file
5. **Verify the selected issue is still real and unresolved:**
   - If `Location` is present and not `N/A`:
     - Read the file(s) mentioned and check if the problem still exists in the current code
     - If **resolved**: remove the entry from `KNOWN_ISSUES.md`, inform user, and **stop**
     - If **still present**: proceed to Step 1 using the issue's description as input
   - If `Location` is missing or `N/A`:
     - Ask the user to confirm whether the issue is still valid based on the description
     - If **no longer valid**: remove the entry from `KNOWN_ISSUES.md`, inform user, and **stop**
     - If **still valid**: proceed to Step 1 using the issue's description as input
6. After the GitHub issue is created, **remove the entry** from `KNOWN_ISSUES.md` (the issue is now tracked on GitHub)

**B) Direct user input** — Normal flow, proceed to Step 1 with user-provided description.

## Step 1: Authenticate

```bash
gh auth status
```

If not authenticated, tell the user to run `gh auth login` and **stop**.

## Step 2: Check for Existing Issues

**Launch a `general-purpose` agent** (via `Agent` tool, **model: haiku**) to perform the dedup check. This keeps the main context clean and fast.

**Agent prompt must include:** the issue summary/keywords, and these exact instructions:

> **IMPORTANT: ONLY use `gh` CLI commands. Do NOT read source code, test files, or explore the repository. Your sole job is to check GitHub issues for duplicates.**
>
> Follow the two-step process below, then return EXACTLY one of: `DUPLICATE #N`, `RELATED #N1 #N2 ...`, or `NO_MATCH`. Keep your response to 1-3 sentences plus the verdict.

### Two-Step Search Process (for the agent)

**Step A — Scan all open issue titles:**

```bash
gh issue list --state open --limit 200 --search "updated:>=YYYY-MM-DD" --json number,title,labels \
  --jq '.[] | "\(.number)\t\(.title)\t\(.labels | map(.name) | join(","))"'
```

Compute the date 6 months ago for the `updated:>=` filter. Scan output for keywords related to the new issue.

**Step B — Deep-read candidates only (max 3):**

For each title that looks related (up to 3), fetch context:

```bash
gh issue view NUMBER
```

Only read body — skip `--comments` unless the body is ambiguous. Determine if it's truly the same issue or just superficially similar.

### Decision rules (agent returns)

- **Exact match** (same root cause/request) → return `DUPLICATE #N`
- **Related but different** → return `RELATED #N1 #N2 ...`
- **No matches** → return `NO_MATCH`

### How to act on the result

- `DUPLICATE #N` → Do NOT create. Tell the user the existing issue. **Stop here.**
- `RELATED #N1 ...` → Proceed, reference in body: `Related: #N1, #N2`
- `NO_MATCH` → Proceed normally.

## Step 3: Classify the Issue

Read `.github/ISSUE_TEMPLATE/` to get the current templates, then match the user's description to the correct template:

| Template | Use When | Labels |
| -------- | -------- | ------ |
| `bug_report.yml` | General bug (host, aicpu, aicore, ring buffer, tensormap, build) | `bug` |
| `feature_request.yml` | New feature or enhancement | `enhancement` |
| `performance_issue.yml` | Performance regression or optimization | `performance` |
| `documentation.yml` | Missing, incorrect, or unclear docs | `documentation` |
| `code_health.yml` | Technical debt, robustness, code quality | `code health` |

**Classification rules:**

- If about a crash, deadlock, incorrect output → `bug_report.yml`
- If about slow execution or regression → `performance_issue.yml`
- If requesting a new capability → `feature_request.yml`
- If about docs being wrong/missing → `documentation.yml`
- If about technical debt, cleanup, missing validation → `code_health.yml`

**If ambiguous**, ask the user to clarify using `AskUserQuestion`.

## Step 4: Gather Required Fields

Each template has **required fields** (marked `required: true` in the YAML). You MUST fill every required field.

**Ask the user** for any required information you cannot infer. Use `AskUserQuestion` for dropdown selections (component, runtime variant, NPU kind, host platform, etc.).

**For fields you can auto-fill:**

- **Git Commit ID**: Run `git rev-parse HEAD` to get the current commit
- **Title prefix**: Use the template's title prefix (`[Bug]`, `[Feature]`, etc.)
- **Host Platform**: Run `uname -s -m` to detect OS and arch. Map to: `Linux aarch64` → `Linux (aarch64)`, `Linux x86_64` → `Linux (x86_64)`, `Darwin arm64` → `macOS (aarch64)`. Fall back to `Other` if unrecognized.
- **NPU Kind**: Run `npu-smi info`, and on failure retry it as `task-submit --run "npu-smi info"` (some shared hosts restrict DCMI to root, so a bare failure does not mean there is no NPU). **Branch on the exit status, not on whether it printed anything** — a DCMI refusal goes to stdout and the retry adds a `task-submit` banner there, so output is non-empty even when the query failed. If both fail, default to `N/A (not hardware-specific)` (or `N/A (simulation only)` for `performance_issue.yml`) and quote the error in the issue so the reason is visible. On success, parse model name to map to Ascend 910B/910C if present.

## Step 5: Format the Issue Body

Since `gh issue create` uses markdown body (not YAML form fields), format the body to match the template structure using markdown sections:

```markdown
### Field Label

Field content here

### Another Field

More content
```

**For dropdown fields**, state the selected value as plain text.

## Step 6: Create the Issue

```bash
gh issue create \
  --title "[Prefix] Short description" \
  --label "label1" --label "label2" \
  --body "$(cat <<'EOF'
### Field 1
content

### Field 2
content
EOF
)"
```

**After creation**, display the issue URL to the user.

## Template Field Reference

### Bug Report (`[Bug]`)

Required: Component (dropdown), Runtime Variant (dropdown), Description, Steps to Reproduce, Expected Behavior, Actual Behavior, Git Commit ID, NPU Kind (dropdown), Host Platform (dropdown)

### Feature Request (`[Feature]`)

Required: Summary, Motivation / Use Case

### Performance Issue (`[Performance]`)

Required: Summary, Runtime Variant (dropdown), Git Commit ID, NPU Kind (dropdown), Host Platform (dropdown), Reproduction, Expected Performance, Actual Performance

### Documentation (`[Docs]`)

Required: Documentation Location, What's Wrong or Missing?

### Code Health (`[Code Health]`)

Required: Category (dropdown), Component (dropdown), Description, Location, Priority (dropdown)

## Checklist

- [ ] Input source determined (KNOWN_ISSUES.md or direct)
- [ ] If from KNOWN_ISSUES.md: issue verified as still real and unresolved
- [ ] gh CLI authenticated
- [ ] Searched for existing issues (no exact duplicate found)
- [ ] Related issues referenced in body (if any)
- [ ] Issue classified to correct template
- [ ] All required fields filled
- [ ] Title uses correct prefix from template
- [ ] Labels match template
- [ ] Body formatted with markdown sections matching template fields
- [ ] Issue created and URL displayed
- [ ] If from KNOWN_ISSUES.md: entry removed from file