creating-issues

name	creating-issues
description	Turns a single feature idea, improvement, or bug into ONE well-structured GitHub issue. TRIGGER when: the user wants to file/open/create an issue, turn a feature idea or improvement into a ticket, or capture something missing or broken as a ticket. DO NOT TRIGGER when: breaking work into multiple issues or planning a body of work → a planning skill; writing a full Product Requirements Document → creating-prd; the idea is still fuzzy and unhardened → grilling-ideas first.
argument-hint	Feature, improvement, or bug to turn into a GitHub issue
compatibility	Requires GitHub access (gh CLI authenticated, or an equivalent GitHub MCP/API tool) and write access to the target repository.
metadata	{"version":"0.1.0","author":"OpsMill"}

Create GitHub Issue

User Input

$ARGUMENTS

Treat $ARGUMENTS as the thing to file. If empty, ask the user what they want to capture before starting.

What this does

Turn a feature idea, improvement, or bug into a single well-structured GitHub issue that matches the repository's own conventions. Keep it small and centred on the need — what is missing or broken, who it affects, and why it matters. Do not propose a solution and do not write acceptance criteria for features — leave the "how" to whoever picks the issue up. Always show the draft and get explicit approval before creating anything.

Core principle

An issue states the need, not the answer. The person (or agent) who implements it decides the approach. For a feature or improvement that means no design, no task breakdown, no acceptance criteria — just a clear problem and its context. For a bug, the "need" is the misbehaviour itself, so reproduction details belong in the issue.

Workflow

1. Learn the repository's conventions

Probe whatever context the repo actually provides — don't assume a fixed layout:

• Read context docs if present: AGENTS.md, CLAUDE.md, CONTEXT.md, README, or a dev/ directory.
• Check for issue templates in .github/ISSUE_TEMPLATE/ and honour them if they exist.
• List the repo's labels (gh label list) and a few recent issues (gh issue list) to match title style, labels, and tone.

If the repo provides an issue template, honour its structure as-is — the fields are there deliberately. The only thing to hold back is prescribing a solution: fill the template's sections with the need and context, not with a design.

2. Classify

Decide whether this is a feature / improvement or a bug. When unsure, ask the user.

3. Draft (need-focused)

Feature / improvement — keep it lean:

## Need

[What's missing or could be better, who it affects, and why it matters now.]

## Context

[Only what's needed to understand the need: relevant area of the product, links to related discussion, constraints. No design.]

## References

- Related issue: #[number]
- Documentation / discussion: [url]

Bug — capture the misbehaviour:

## What happens

[Observed behaviour.]

## What should happen

[Expected behaviour.]

## Steps to reproduce

1. ...
2. ...

## Environment

[Version, OS, configuration, or other relevant context.]

## References

- Related issue: #[number]
- Logs / screenshots: [link or `<details>` block]

Draft a clear, searchable title using the repo's convention (e.g. feat:, fix:, or whatever recent issues use), and pick labels from the repo's existing set.

4. Get approval, then create

By default, present the full draft (title, labels, body) to the user and wait for explicit approval before creating the issue — even when you have permission to create it directly. The gate exists to stop silent creation from mere permission; it is not meant to override a direct instruction.

If the user has explicitly told you to file it without review (e.g. "just file it, don't ask"), honour that — but still echo the final title, labels, and body in your reply before (or as) you create it, so there's a record of what went out.

Create the issue with the available tooling, for example:

gh issue create --title "[TITLE]" --body "[BODY]" --label "[LABELS]"

--label takes a comma-separated list (--label 'bug,enhancement') — a space-separated value is treated as a single label name.

Or the equivalent GitHub MCP call. Return the issue URL.

Quality gates

Per ../quality-gates/gates/gate-model.md. creating-issues is Tier 0; the existing user-approval step IS the independent judgment (R4) — no subagent is added.

Gate	Trigger	Tier	Primitives	Pass criteria	On-fail
Draft-shown	before gh issue create	T0	P1 + human approval	The full draft is shown and the user approves.	revise per feedback

Guardrails

• Prefer clarity over completeness — a short, sharp issue beats a padded one.
• Resist scope creep: one need per issue. If the input contains several, surface that and ask whether to split.
• Don't invent labels, milestones, or assignees that don't exist in the repo.
• Don't smuggle a solution into the "Need" or "Context" — if you catch yourself describing how, cut it.