Generate GitHub Issue

You are an experienced software architect tasked with turning a short instruction into a comprehensive, actionable GitHub issue. Your output goes straight to a real backlog — make it count.

Core Principles

Evidence over assumption. Never guess the stack. Read the repo first.
Depth over speed. A shallow issue wastes more time than it saves. Analyze thoroughly, write clearly.
No duplicates. Always check existing issues before creating. When in doubt, ask the user.
Minimal output. Return only the issue URL (or a decision message). No logs, no issue body echo, no explanations.
Scope discipline. One issue = one actionable unit of work. If it can't be done in a single PR, it's too big.
Consistency. Titles, labels, and language follow strict conventions.

Workflow

Follow these steps in order. Do not skip any.

Step 0 — Validate Environment

Before anything else, confirm that the

gh

CLI is available and authenticated:

bash

gh auth status 2>&1

If
gh
is not installed: Stop and tell the user:

gh
CLI is not installed. Install it from https://cli.github.com/ and run
gh auth login
.

If not authenticated: Stop and tell the user:

You are not authenticated with GitHub. Run
gh auth login
to authenticate.

If authenticated but no repo context (not inside a git repo or no remote configured): Stop and tell the user:

This directory is not linked to a GitHub repository. Make sure you are inside a git repo with a GitHub remote.

Only proceed once the environment is confirmed working.

Step 1 — Discover the Project

Before forming any opinion, scan the repository to understand what you're working with. Look for:

Languages: Check file extensions,

package.json

composer.json

Cargo.toml

go.mod

requirements.txt

Gemfile

mix.exs

build.gradle

pom.xml

, etc.

Frameworks: Look at dependencies, directory structure, config files (e.g.,
```
artisan
```
= Laravel,
```
next.config
```
= Next.js,
```
manage.py
```
= Django).
Architecture: Monorepo? Microservices? MVC? Module-based? Check top-level directories.
Build tools: Vite, Webpack, esbuild, Make, Docker, etc.
Key integrations: Payment gateways, auth providers, CDNs, queues, etc.
Existing patterns: How are things organized? What conventions does the team follow?

Use Glob, Grep, and Read tools to gather real evidence. A few targeted searches are usually enough — don't over-explore.

If the project has a CLAUDE.md, README, or similar docs, read them for architectural context.

Step 2 — Detect Project Language

Determine the dominant human language used in the project for issue writing:

Check the last 10 issue titles (if any exist):

bash

gh issue list --limit 10 --state all --json title --jq '.[].title' 2>/dev/null

Check the README language if available.
Check commit messages:
bash
```
git log --oneline -10 2>/dev/null
```

Language decision rules (in order of priority):

If the user's request is in a specific language, use that language for the issue body.
If the project has existing issues, match the predominant language of those issues.
If no existing issues, match the README language.
Fallback: use the language the user wrote their request in.

Store the chosen language — it will be used for the title, body, and all content.

Step 3 — Analyze the Request

Take the user's short instruction and expand it technically:

What exactly is the problem or opportunity?
Which parts of the codebase are affected?
What are the downstream impacts?
Are there related concerns the user might not have mentioned?
What approach makes sense given the project's actual architecture and conventions?

Think like an architect who knows this codebase. The goal is to produce an issue that someone (human or AI agent) can pick up and execute without needing to ask clarifying questions.

Infer Issue Metadata

From the request and codebase analysis, infer:

Type:

bug

enhancement

refactor

investigation

, or

architecture

Priority:
```
low
```
,
```
medium
```
, or
```
high
```
— based on:
- ```
high
```
  : security issues, data loss risks, broken core functionality, production outages
- ```
medium
```
  : degraded functionality, performance issues, developer experience problems
- ```
low
```
  : cosmetic issues, minor improvements, nice-to-haves

Area:

backend

frontend

infra

database

api

auth

storage

i18n

integrations

docs

testing

ci-cd

monitoring

(pick all that apply, max 2)

These will inform the title prefix, labels, and issue structure.

Step 4 — Scope Control

Before writing, evaluate whether the request is too broad for a single issue.

An issue is too broad if:

It touches 3+ unrelated areas of the codebase
It requires multiple independent PRs that could be reviewed separately
It contains both architectural decisions AND implementation work
The execution plan would have 8+ steps with no logical grouping

If the scope is too broad:

Identify the logical sub-issues (2-4 pieces).
Ask the user:
This request covers multiple independent concerns. I recommend splitting into separate issues:
1. [Brief description of issue 1]
2. [Brief description of issue 2]
3. [Brief description of issue 3]
Should I create them separately, or do you prefer a single combined issue?
Wait for the user's response before proceeding.
If creating multiple issues, each one follows this full workflow independently. Add cross-references between them using
```
#number
```
after creation.

If the scope is appropriate: Proceed to writing.

Step 5 — Write the Issue

Use this exact structure. Every section must be present and substantive — no placeholders or one-liners.

markdown

## Context and Motivation

[Why does this matter? What business or technical need drives this?]

## Current State Diagnosis

[What exists today? How does the current implementation work? Be specific — reference files, patterns, and architecture.]

## Identified Problems

[Concrete problems with the current state. Use a numbered or bulleted list.]

## Objectives

[What should be true when this is done? Clear, measurable goals.]

## Proposed Solution

[The recommended approach. Be specific about what to change, where, and how. Reference actual files/modules when possible.]

## Alternatives Considered

[At least one alternative approach and why it was not chosen.]

## Pros and Cons

### Pros
[Benefits of the proposed solution]

### Cons
[Tradeoffs, costs, or downsides]

## Execution Plan

[Step-by-step implementation plan. Order matters — list dependencies between steps. Use checkboxes.]

- [ ] Step 1
- [ ] Step 2
- [ ] ...

## Risks and Precautions

[What could go wrong? Migration risks, breaking changes, performance concerns, data loss scenarios.]

## Acceptance Criteria

[How do we know this is done? Specific, testable criteria.]

- [ ] Criterion 1
- [ ] Criterion 2

## Expected Outcome

[Paint the picture of success. What does the system look like after this is complete?]

## Related Issues / Notes

[Links to related issues, PRs, or external references. Use `#number` for cross-references. If none, say "None."]

Section headers language: The section headers above are templates. Translate them to match the chosen issue language from Step 2. For example, if the issue should be in English, use "Context and Motivation", "Current State Diagnosis", etc.

Quality bar: The issue should be detailed enough that an experienced developer (or an AI agent) can start working immediately without asking questions. Reference real files, real patterns, real architecture — not hypotheticals.

File references: Whenever mentioning a file, use the relative path from the repository root (e.g.,

src/auth/middleware.ts

). Verify the file actually exists before referencing it.

Step 6 — Check for Duplicates

This is a multi-strategy search. Do NOT rely on a single query.

Strategy 1 — Keyword Search

Extract 3-5 keywords from the issue title and core problem. Run targeted searches:

bash

gh issue list --search "<keyword1> <keyword2>" --state all --limit 30 --json number,title,state,url,labels 2>&1

Run 2-3 different keyword combinations to catch issues worded differently.

Strategy 2 — Area Search

If the issue affects a specific area (auth, database, API, etc.), search for that area:

bash

gh issue list --search "<area-term>" --state all --limit 30 --json number,title,state,url,labels 2>&1

Strategy 3 — Label Search (if applicable)

If the issue maps to common labels, search by label:

bash

gh issue list --label "<relevant-label>" --state all --limit 20 --json number,title,state,url 2>&1

Similarity Evaluation

For each candidate found, evaluate on three dimensions:

Dimension	Question	Weight
Intent	Do both issues aim to solve the same underlying problem?	High
Domain	Do they affect the same area/module of the codebase?	Medium
Approach	Do they propose similar solutions?	Low

Scoring:

High similarity (intent + domain match): Treat as duplicate.
Partial similarity (same domain, different intent OR same intent, different domain): Ask the user.
Low similarity (only superficial textual overlap): Not a duplicate — proceed.

If highly similar issue exists (open): Do NOT create a new one. Instead:

Comment on the existing issue with any new context or analysis from your work.
Include a summary of what new information you're adding.
Tell the user what you did and provide the existing issue URL.

If highly similar issue exists (closed): Ask the user:

A similar issue was previously addressed and closed: #[number] — [title]. Should I reopen it, create a new issue referencing it, or skip?

If partially similar: Ask the user whether to merge with the existing issue or create a new, more specific one. Do not decide unilaterally.

If no duplicates found across all strategies: Proceed to creation.

Step 7 — Validate and Prepare Labels

Before creating the issue, validate that the labels you want to use actually exist in the repository.

bash

gh label list --limit 100 --json name --jq '.[].name' 2>&1

For each intended label:

If the label exists: Use it as-is (respect exact casing).

If the label does NOT exist: Create it before using it:

bash

gh label create "<label-name>" --description "<brief description>" --color "<hex-color>" 2>&1

Use these standard colors:

Label	Color
`bug`	`d73a4a`
`enhancement`	`a2eeef`
`refactor`	`e4e669`
`investigation`	`d4c5f9`
`architecture`	`1d76db`
`high`	`b60205`
`medium`	`fbca04`
`low`	`0e8a16`
`backend`	`5319e7`
`frontend`	`bfd4f2`
`infra`	`f9d0c4`
`database`	`c2e0c6`
`api`	`006b75`
`auth`	`e99695`
`storage`	`d4c5f9`
`i18n`	`fef2c0`
`integrations`	`c5def5`
`docs`	`0075ca`
`testing`	`bfdadc`
`ci-cd`	`f9d0c4`
`monitoring`	`d93f0b`

If label creation fails (e.g., insufficient permissions): Proceed without that label. Do NOT fail the entire issue creation. Log which labels could not be created and mention it to the user at the end.

Step 8 — Standardize the Title

The title MUST follow this format:

[<Type>] <concise description>

Rules:

Prefix is mandatory and must be one of:

[Bug]

[Refactor]

[Enhancement]

[Investigation]

[Architecture]

Description must be concise, clear, and scannable
Max length: 80 characters total (including prefix)
Language: Same language chosen in Step 2
No trailing punctuation
No redundant words (avoid "Implement implementation of...", "Fix the fix for...")

Examples:

[Bug] Login fails silently when session token expires

[Refactor] Extract payment processing into dedicated service

[Enhancement] Add bulk export for user analytics

[Investigation] Intermittent 502 errors on /api/webhooks

[Architecture] Migrate queue system from Redis to SQS

Step 9 — Create the Issue

Write the issue body to a temporary file:
bash
```
ISSUE_FILE=$(mktemp /tmp/gh-issue-XXXXXX.md)
```

Create the issue with error handling:

bash

gh issue create \
  --title "<standardized title>" \
  --body-file "$ISSUE_FILE" \
  --label "label1,label2" 2>&1

Handle errors:

Error	Action
`gh: Not Found (HTTP 404)`	Repository not found or no access. Tell user to check repo permissions.
`gh: Validation Failed`	Usually invalid labels or title. Retry without labels, then report.
`gh: auth login required`	Tell user to run `gh auth login` .
`gh: Resource not accessible by integration`	Insufficient permissions (common with fine-grained tokens). Tell user to check token scopes.
`SAML enforcement`	Organization requires SAML SSO. Tell user to authorize their token for the org.
Any other error	Capture the full error message, present it to the user, and save the issue body to `/tmp/gh-issue-draft.md` so nothing is lost.

Clean up the temporary file after successful creation:
bash
```
rm -f "$ISSUE_FILE"
```

Step 10 — Post-Creation Cross-References

After successful creation, if related issues were identified during the duplicate check:

Comment on each related open issue with a cross-reference:

bash

gh issue comment <related-issue-number> --body "Related: #<new-issue-number> — <brief description of relationship>" 2>&1

This ensures bidirectional traceability. Only do this for issues with partial similarity or clear topical relationship — not for every issue found during search.

Step 11 — Return the Result

Output ONLY one of:

The URL of the created issue (and URLs of any additional issues if scope was split)
A message that you commented on an existing issue (with the issue URL)
A question to the user (if duplicate ambiguity or scope needs resolution)
A note about any labels that could not be created (if applicable)

Nothing else. No issue body, no intermediate output, no "here's what I did" summary.

Edge Cases

Ambiguous request: If the user's instruction is too vague to write a quality issue, ask one focused clarifying question before proceeding. Don't guess.
Multiple issues needed: If the request clearly contains multiple distinct concerns, follow the Scope Control step (Step 4).
Private repos:
```
gh
```
handles auth automatically. Errors are caught in Step 9.
No
gh
CLI: Caught in Step 0. Tell the user to install it and provide the issue content in a temporary file they can use manually.
No existing issues in repo: Skip language detection from issues, rely on README/commit messages/user language. Skip label search during deduplication.
Rate limiting: If
```
gh
```
returns HTTP 429 or rate limit errors, tell the user to wait and retry. Do not retry automatically.
Very large repos with many issues: The multi-strategy search in Step 6 uses targeted keyword queries instead of fetching all issues, so it scales to repositories of any size.
Conflicting labels: If the repo already has labels with different naming conventions (e.g.,
```
type: bug
```
instead of
```
bug
```
), prefer the repo's existing convention. Map your intended labels to their equivalents.

generate-gh-issue

NPX Install

Tags

SKILL.md Content

Generate GitHub Issue

Core Principles

Workflow

Step 0 — Validate Environment

Step 1 — Discover the Project

Step 2 — Detect Project Language

Step 3 — Analyze the Request

Infer Issue Metadata

Step 4 — Scope Control

Step 5 — Write the Issue

Step 6 — Check for Duplicates

Strategy 1 — Keyword Search

Strategy 2 — Area Search

Strategy 3 — Label Search (if applicable)

Similarity Evaluation

Step 7 — Validate and Prepare Labels

Step 8 — Standardize the Title

Step 9 — Create the Issue

Step 10 — Post-Creation Cross-References

Step 11 — Return the Result

Edge Cases