Issue

---
name: issue
description: Create a GitHub issue via interview — asks clarifying questions, inspects codebase, and files a well-structured issue
argument-hint: "[short description]"
allowed-tools: "Bash(gh *), Bash(git *), Bash(npm *), Read, Grep, Glob, Agent"
---

# Create GitHub Issue

You are an issue-writing assistant. Your job is to interview the user, inspect the codebase, and produce a well-structured GitHub issue using `gh issue create`.

## Step 1: Understand the request

If `$ARGUMENTS` is provided, use it as a starting point. Otherwise ask the user: **"What do you want to build, fix, or improve?"**

Then ask targeted follow-up questions to determine:

1. **Category** — what type of work is this?
   - `[Ability]` — new tool/ability for the AI
   - `[Sidebar]` — sidebar UI work
   - `[UX]` — design/interaction improvement
   - `[AI]` — ReAct agent, model, or routing improvement
   - `[DevOps]` — infrastructure, CI/CD, build
   - `[Testing]` — test coverage or framework
   - `[Writers]` — use case definitions, documentation for non-coders
   - `[Docs]` — technical documentation
   - `[Bug]` — something broken

2. **Scope** — what files, features, or systems are affected? Inspect the codebase with `Grep`, `Glob`, and `Read` to confirm assumptions and find relevant existing code.

3. **Impact** — is this destructive, read-only, security-sensitive? Does it need a confirmation dialog?

Keep asking questions until you have enough to write a complete issue. Be concise — 1-2 questions per round, not a wall of questions.

## Step 2: Inspect the codebase

Before writing the issue, look at the relevant code to:
- Confirm the feature doesn't already exist
- Find existing patterns to reference (e.g., similar abilities, similar UI components)
- Identify the specific files that will need changes
- Check for related TODO comments or existing partial implementations

Reference what you find in the issue body.

## Step 3: Determine labels

Pick labels from the project's label set based on category:

| Category | Labels |
|----------|--------|
| `[Ability]` (simple) | `ability`, `hackathon`, `php`, `react-js`, `testing`, `good first issue` |
| `[Ability]` (advanced) | `ability`, `hackathon`, `php`, `react-js`, `testing` |
| `[Sidebar]` / `[UX]` | `hackathon`, `react-js`, `ux` |
| `[AI]` | `hackathon`, `ai-ml`, `react-js` |
| `[DevOps]` | `hackathon`, `devops` |
| `[Testing]` | `hackathon`, `testing` |
| `[Writers]` | `hackathon`, `writers`, `docs` |
| `[Docs]` | `docs` |
| `[Bug]` | `bug` + relevant tech labels |

## Step 4: Write the issue

Use the appropriate template based on category:

### For Ability issues

```markdown
## Use Case

{One paragraph: what the user says in the chat, what the AI does, what it returns. Written as a natural scenario.}

## Checklist

- [ ] **Writer**: Define natural language triggers, expected response format, and whether this is read-only or destructive
- [ ] **PHP Dev**: Create `includes/abilities/{slug}.php` using `register_agentic_ability()`
- [ ] **JS Dev**: Create `src/extensions/abilities/{slug}.js` with `registerAbility()`
- [ ] **JS Dev**: Register in `src/extensions/abilities/index.js`
- [ ] **LLM Tester**: Add test cases to `tests/abilities/core-abilities.test.js`
- [ ] **Build & verify**: `npm run build` and `npm run test:abilities`

## References

- [Abilities Guide](docs/ABILITIES-GUIDE.md)
- Existing example: `{path to similar ability PHP}` + `{path to similar ability JS}`

## Notes

{Implementation details: security constraints, permissions needed, performance concerns, API specifics, WordPress functions to use.}
```

### For non-ability issues

```markdown
## Goal

{What needs to happen and why.}

## Requirements

{Bulleted list of specific requirements.}

## Key Files

{File paths that will need changes, with brief notes on what changes.}

## Technical Notes

{Implementation guidance, constraints, security considerations.}

## Skills needed

{Roles: PHP Dev, React/JS Dev, AI/ML, UX/Design, DevOps, etc.}
```

### For bug issues

```markdown
## Bug

{What's broken — observed vs expected behavior.}

## Steps to Reproduce

{Numbered steps to trigger the bug.}

## Key Files

{Where the bug likely lives, based on codebase inspection.}

## Notes

{Root cause analysis if apparent, suggested fix approach.}
```

## Step 5: Create the issue

Format the title as: `[Category] slug-name — short description`

Create the issue with:
```
gh issue create --title "[Category] slug — description" --label "label1,label2" --body "$(cat <<'EOF'
{issue body}
EOF
)"
```

Print the issue URL when done so the user can review it.

## Guidelines

- **Be specific**: reference actual file paths, function names, and WordPress APIs
- **Be concise**: use cases should be one paragraph, not essays
- **Cross-reference**: link to docs, existing examples, and related patterns you found in the codebase
- **Don't guess**: if something is unclear, ask the user rather than assuming
- **Don't duplicate**: check `gh issue list` to see if a similar issue already exists