---

name: create-github-issues locale: caveman-lite source_locale: en source_commit: 82c77053 fence_basis_commit: 82c77053 translator: "Julius Brussee homage — caveman" translation_date: "2026-04-19" description: > Structured GitHub issue creation from review findings or task breakdowns. Groups related findings into logical issues, applies labels, and produces issues with standard templates including summary, findings, and acceptance criteria. Designed to consume output from review-codebase or similar review skills. license: MIT allowed-tools: Read Bash Grep Glob metadata: author: Philipp Thoss version: "1.0" domain: git complexity: intermediate language: multi tags: git, github, project-management, issues, review, automation

Create GitHub Issues

Structured GitHub issue creation from review findings or task breakdowns. Converts a list of findings (from review-codebase, security-audit-codebase, or manual analysis) into well-formed GitHub issues with labels, acceptance criteria, and cross-references.

When to Use

• After a codebase review produces a findings table that needs tracking
• After a planning session identifies work items that should become issues
• When converting a TODO list or backlog into trackable GitHub issues
• When batch-creating related issues that need consistent formatting and labeling

Inputs

• Required: findings — a list of items, each with at minimum a title and description. Ideally also includes: severity, affected files, and suggested labels
• Optional:
  • group_by — how to batch findings into issues: severity, file, theme (default: theme)
  • label_prefix — prefix for auto-created labels (default: none)
  • create_labels — whether to create missing labels (default: true)
  • dry_run — preview issues without creating them (default: false)

Procedure

Step 1: Prepare Labels

Ensure all needed labels exist in the repository.

1. List existing labels: gh label list --limit 100
2. Identify labels needed by the findings (from severity, phase, or explicit label fields)
3. Map severities to labels if not already mapped: critical, high-priority, medium-priority, low-priority
4. Map phases/themes to labels: security, architecture, code-quality, accessibility, testing, performance
5. If create_labels is true, create missing labels: gh label create "name" --color "hex" --description "desc"
6. Use consistent colors: red for critical/security, orange for high, yellow for medium, blue for architecture, green for testing

Got: All labels referenced by findings exist in the repository. No duplicate labels created.

If fail: If gh CLI is not authenticated, instruct the user to run gh auth login. If label creation is denied (insufficient permissions), proceed without creating labels and note which labels are missing.

Step 2: Group Findings

Batch related findings into logical issues to avoid issue sprawl.

1. If group_by is theme: group findings by their phase or category (all security findings → 1-2 issues, all a11y → 1 issue)
2. If group_by is severity: group findings by severity level (all CRITICAL → 1 issue, all HIGH → 1 issue)
3. If group_by is file: group findings by primary affected file
4. Within each group, order findings by severity (CRITICAL first)
5. If a group has more than 8 findings, split into sub-groups by sub-theme
6. Each group becomes one GitHub issue

Got: A set of issue groups, each containing 1-8 related findings. The total number of issues should be manageable (typically 5-15 for a full codebase review).

If fail: If findings have no grouping metadata, fall back to one issue per finding. This is acceptable for small finding sets (< 10) but produces too many issues for larger sets.

Step 3: Compose Issues

Build each issue using a standard template.

1. Title: [Severity] Theme: Brief description — e.g., [HIGH] Security: Eliminate innerHTML injection in panel.js
2. Body structure:

   ## Summary
   One-paragraph overview of what this issue addresses and why it matters.
   
   ## Findings
   1. **[SEVERITY]** Finding description (`file.js:line`) — brief explanation
   2. **[SEVERITY]** Finding description (`file.js:line`) — brief explanation
   
   ## Acceptance Criteria
   - [ ] Criterion derived from finding 1
   - [ ] Criterion derived from finding 2
   - [ ] All changes pass existing tests
   
   ## Context
   Generated from codebase review on YYYY-MM-DD.
   Related: #issue_numbers (if applicable)
   

3. Apply labels: severity label + theme label + any custom labels
4. If findings reference specific files, mention them in the body (not as assignees)

Got: Each issue has a clear title, numbered findings with severity badges, checkbox acceptance criteria, and appropriate labels.

If fail: If the body exceeds GitHub's issue size limit (65536 chars), split the issue into parts and cross-reference them.

Step 4: Create Issues

Create the issues using gh CLI and report results.

1. If dry_run is true, print each issue title and body without creating, then stop
2. For each composed issue, create it:

   gh issue create --title "title" --body "$(cat <<'EOF'
   body content
   EOF
   )" --label "label1,label2"
   

3. Record the URL of each created issue
4. After all issues are created, print a summary table: #number | Title | Labels | Findings count
5. If issues should be sequenced, add cross-references: edit the first issue to mention "Blocked by #X" or "See also #Y"

Got: All issues created successfully. A summary table with issue numbers and URLs is printed.

If fail: If an individual issue fails to create, log the error and continue with remaining issues. Report failures at the end. Common failures: authentication expired, label not found (if create_labels was false), network timeout.

Validation

• All findings are represented in at least one issue
• Each issue has at least one label
• Each issue has checkbox acceptance criteria
• No duplicate issues were created (check titles against existing open issues)
• Issue count is reasonable for the finding count (not 1:1 for large sets)
• Summary table was printed with all issue URLs

Pitfalls

• Issue sprawl: Creating one issue per finding produces 20+ issues that are hard to manage. Group aggressively — 5-10 issues from a full review is ideal
• Missing acceptance criteria: Issues without checkboxes cannot be verified as complete. Every finding should map to at least one checkbox
• Label chaos: Creating too many labels makes filtering useless. Stick to severity + theme, not per-finding labels
• Stale references: If creating issues from an old review, verify findings still apply before creating issues. Code may have changed
• Forgetting dry run: For large finding sets, always preview with dry_run: true first. It is much easier to edit a plan than to close 15 incorrect issues

Related Skills

• review-codebase — produces the findings table this skill consumes
• review-pull-request — produces PR-scoped findings that can also be converted to issues
• manage-backlog — organizes issues into sprints and priorities after creation
• create-pull-request — creates PRs that reference and close the issues
• commit-changes — commits the fixes that resolve the issues