Create Issue

---
name: create-issue
description: Create a well-structured GitHub issue with duplicate detection, code verification, and auto-labeling
argument-hint: [brief description]
---

# Interactive Issue Creation

Create a GitHub issue with a standardized structure, duplicate detection, code verification, and auto-labeling.

## 1. Gather Initial Context

### 1a. Determine the starting input

- If `$ARGUMENTS` contains a text description, use it as the initial context.
- If `$ARGUMENTS` is empty, ask using `AskUserQuestion`:
  > "Describe the issue you want to create. A sentence or two is enough -- I'll help structure it."

### 1b. Ask for additional context

Ask using `AskUserQuestion`:

> "Do you have any links with additional context (e.g., error logs, screenshots, related discussions)?"

Options:
1. **Yes, here's a link** - The user will paste a URL.
2. **No, let's continue with what I described** - Proceed without external context.

## 2. Deep Understanding -- Clarify Until Crystal Clear

**This step is mandatory and must not be skipped.** Before moving forward, you must be fully confident that you understand exactly what the user wants.

### 2a. Summarize your understanding

Write a short, concrete summary of:
- **What** the user is describing (the problem, feature, or improvement)
- **Why** it matters (impact, who is affected, what breaks or is missing)
- **Where** in the system it applies (which feature domains, widgets, providers, or models)

### 2b. Identify gaps and ambiguities

Critically evaluate your summary. Ask yourself:
- Could this description mean two different things?
- Is the scope clear -- do I know what's in and what's out?
- For bugs: Do I know the exact reproduction path, or am I guessing?
- For features/improvements: Do I know the desired behavior precisely, or is it vague?

### 2c. Ask clarifying questions (repeat until clear)

If **any** gap or ambiguity exists, ask clarifying questions. **Ask one question at a time** using `AskUserQuestion` with options when applicable. Do not proceed until every question is answered. Common clarifications:

- "When you say X, do you mean A or B?"
- "What is the expected behavior? What should happen instead?"
- "Is this limited to [feature domain], or does it affect other areas too?"
- "Can you give me a concrete example or scenario?"

**Rules for this step:**
- **One question at a time.** Never dump multiple questions in a single message.
- **Never assume.** If something could be interpreted two ways, ask.
- **Iterate.** If the user's answer raises new questions, ask those too.
- **Don't interrogate unnecessarily.** If the description is genuinely clear, a brief confirmation is enough.

Once you are confident you understand the issue completely, proceed to Step 3.

## 3. Determine Issue Type

Analyze the combined context and infer the issue type:

- **Bug** - Something is broken or behaving incorrectly
- **Feature** - A new capability that doesn't exist yet
- **Improvement** - Enhancement to an existing feature
- **Task** - Refactors, chores, and other specific pieces of work

Only ask using `AskUserQuestion` if the type is truly ambiguous. Otherwise, infer silently and confirm later in the combined review (Step 8).

Store the selected type as `ISSUE_TYPE`.

## 4. Investigate the Codebase

Before structuring the issue, investigate the relevant code:

1. **Identify affected areas**: Determine which feature domains (ingredients, recipes, menu, shopping, theme, flutter_essentials) are involved.
2. **Search the codebase**: Find the relevant code paths, providers, models, and widgets.
3. **For bugs**: Verify the bug actually exists in the current code. If the code looks correct:
   - Report to the user: "I checked the code and this appears to already be handled in `<file>:<line>`. Are you sure you want to create this issue?"
   - If the user confirms, proceed. If not, stop.
4. **For features/improvements**: Identify the existing code that would need to change, and any patterns already in place. Run the **pattern-scout** agent if a new pattern is being introduced.
5. **Check relevant ADRs**: Run the **adr-checker** agent in consult mode to find ADRs that affect the planned work.

Store findings as `CODE_CONTEXT`.

## 5. Search for Duplicates and Related Issues

### 5a. Search open issues

```bash
gh issue list --state open --limit 100 --json number,title,labels,body

5b. Search recently closed issues

gh issue list --state closed --limit 50 --json number,title,labels,body

5c. Analyze matches

Compare the new issue's intent against fetched issues. Look for:

• Exact duplicates: Same problem described differently.
• Related issues: Issues that touch the same area or feature.
• Closed duplicates: Issues that were already resolved.

5d. Report findings

If likely duplicates are found:

Ask using AskUserQuestion:

"I found an existing issue that looks like it covers the same problem:

• # -