Generate GitHub Issue

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

Step 0 — Validate Environment

gh

gh auth status 2>&1

gh

gh

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

gh auth login

.

You are not authenticated with GitHub. Run

gh auth login

to authenticate.

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

Step 1 — Discover the Project

• 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?

Step 2 — Detect Project Language

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

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

2. Check the README language if available.
3. Check commit messages:
   bash

   git log --oneline -10 2>/dev/null

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

Step 3 — Analyze the Request

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

Infer Issue Metadata

• 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)

Step 4 — Scope Control

• 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

1. Identify the logical sub-issues (2-4 pieces).
2. 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?

3. Wait for the user's response before proceeding.
4. If creating multiple issues, each one follows this full workflow independently. Add cross-references between them using

   #number

   after creation.

Step 5 — Write the Issue

## 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."]

src/auth/middleware.ts

Step 6 — Check for Duplicates

Strategy 1 — Keyword Search

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

Strategy 2 — Area Search

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

Strategy 3 — Label Search (if applicable)

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

Similarity Evaluation

• 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.

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

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

Step 7 — Validate and Prepare Labels

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

1. If the label exists: Use it as-is (respect exact casing).
2. 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

[<Type>] <concise description>

• 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...")

• [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

1. Write the issue body to a temporary file:
   bash

   ISSUE_FILE=$(mktemp /tmp/gh-issue-XXXXXX.md)

2. Create the issue with error handling:
   bash

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

3. 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.

4. Clean up the temporary file after successful creation:
   bash

   rm -f "$ISSUE_FILE"

Step 10 — Post-Creation Cross-References

1. 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

2. 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

• 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)

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.