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

## 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

## 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

## 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