GitHub Issues

name description

github-issue

Create and manage standalone GitHub issues. Use this for creating new independent issues, stories, bugs, or feature requests that are NOT part of another issue. For issues that belong to a parent issue, use the github-sub-issue skill instead.

GitHub Issues/

Create and manage standalone GitHub issues using the gh issue CLI.

When to Use This Skill vs github-sub-issue

Use THIS skill (github-issue) Use github-sub-issue

Creating a new standalone story/​feature Breaking down an existing issue into tasks

Reporting a new bug Creating implementation tasks for a parent issue

Creating independent work items Linking existing issues to a parent

Top-level issues with no parent Child issues that are part of a bigger story

Rule of thumb: If the issue can stand alone and makes sense without referencing another issue, use this skill. If it's a piece of a larger issue, use github-sub-issue .

Creating Issues

gh issue create --title " <title> " [options]

Common flags:

--title, -t : Issue title (required, or will prompt)

--body, -b : Issue body/​description

--body-file, -F : Read body from file (use - for stdin)

--label, -l : Add labels (can be used multiple times)

--assignee, -a : Assign users ( @me for self-assign)

--milestone, -m : Add to milestone by name

--project, -p : Add to project by title

--template, -T : Use an issue template

--repo, -R : Target repository (OWNER/​REPO format)

Examples

Simple issue:

gh issue create --title " Add dark mode support " --body " Users should be able to toggle dark mode in settings "

Bug report with labels:

gh issue create
--title " fix(api): settlement resources not updating "
--body " Resources are not being recalculated after building construction completes. "
--label bug
--label backend
--label " severity:medium "

Feature request with assignment and project:

gh issue create
--title " feat(game): implement trading between settlements "
--body " Players should be able to trade resources with other settlements. "
--label enhancement
--label backend
--label frontend
--assignee @me
--project " <Project Name> "

Using a body file (for longer descriptions):

gh issue create
--title " feat(frontend): redesign settlement view "
--body-file /​tmp/​issue-body.md
--label frontend
--label enhancement

Using HEREDOC for body (recommended for complex issues):

gh issue create --title " feat(game): building upgrade system " --body " $( cat << ' EOF '

Summary

Implement a system for upgrading buildings to higher levels.

Requirements

• Buildings can be upgraded to increase their effectiveness
• Each upgrade level requires more resources and time
• Visual indicator for building level in settlement view

Acceptance Criteria

• Backend: UpgradeBuildingAction implemented
• Backend: Building levels stored in database
• Frontend: Upgrade button in building details panel
• Frontend: Level indicator on building sprites

Technical Notes

See docs/​game/​BUILDINGS.md for building registry patterns. EOF ) " --label enhancement --label backend --label frontend

Labeling (MANDATORY)

Every issue MUST have appropriate labels. Add them at creation time using --label flags.

When to Add Labels

At creation time (preferred):

gh issue create --title " ... " --body " ... " --label bug --label backend --label " severity:medium "

After creation :

gh issue edit < issue-number > --add-label frontend --add-label enhancement

Required Labels

Every issue MUST have:

One type label - What kind of work is this?

One or more area labels - Which part(s) of the codebase?

Severity label - Required for bugs only

All Available Labels

Type Labels (pick one)

Label When to Use

bug Something isn't working as expected. Always pair with a severity label.

enhancement New feature or improvement to existing functionality.

documentation Improvements or additions to documentation only.

question Further information is requested before work can proceed.

suggestion An idea or proposal that needs discussion before becoming a task.

Area Labels (pick one or more)

Label When to Use

frontend Work involves React components, TypeScript, CSS, or frontend architecture.

backend Work involves PHP/​Symfony, API endpoints, services, or database operations.

infrastructure Work involves Terraform, AWS, CI/​CD, or deployment configuration.

sprite Work involves creating or modifying sprite/​icon artwork assets.

Severity Labels (required for bugs)

Label When to Use

severity:critical System is down, data loss occurring, or security vulnerability. Requires immediate attention.

severity:high Major functionality is broken with no workaround. Blocks significant user workflows.

severity:medium Feature is impaired but workarounds exist. Can wait for next sprint.

severity:low Minor issue, cosmetic problem, or edge case. Fix when convenient.

Priority Labels (optional)

Label When to Use

priority: high Issue should be prioritized above others in the current sprint.

Workflow Labels (rarely used)

Label When to Use

good first issue Simple issue suitable for newcomers to the codebase.

help wanted Extra attention is needed; looking for contributors.

duplicate This issue already exists elsewhere. Close with reference to original.

invalid This doesn't seem right or is based on incorrect assumptions.

wontfix This will not be worked on. Close with explanation.

Labeling Examples

Bug report:

--label bug --label backend --label " severity:medium "

New feature spanning frontend and backend:

--label enhancement --label frontend --label backend

Critical production bug:

--label bug --label backend --label " severity:critical " --label " priority: high "

Documentation update:

--label documentation

Sprite work:

--label enhancement --label sprite

Other Issue Commands

List issues

List open issues

gh issue list

List with filters

gh issue list --label bug --state open gh issue list --assignee @me gh issue list --milestone " v1.0 "

View an issue

gh issue view 123 gh issue view 123 --web # Open in browser

Edit an issue

gh issue edit 123 --title " New title " gh issue edit 123 --add-label " priority: high " gh issue edit 123 --remove-label " bug " gh issue edit 123 --add-assignee username

Close an issue

gh issue close 123 gh issue close 123 --comment " Fixed in PR #456 " gh issue close 123 --reason " not planned "

Comment on an issue

gh issue comment 123 --body " Working on this now "

Project Board & Assignment (MANDATORY)

After creating ANY issue, you MUST complete these steps:

1. Add to Project Board

gh project item-add 3 --owner naroga --url < issue-url >

1. Assign to @naroga

gh issue edit < issue-number > --add-assignee naroga

1. Place in Current Sprint (if applicable)

Get the item ID for the issue in the project

ITEM_ID= $( gh project item-list 3 --owner naroga --format json | jq -r ' .items[] | select(.content.number == <ISSUE_NUMBER>) | .id ' )

Update sprint/​iteration field to current

gh project item-edit --project-id PVT_kwHOADWTbc4BHvAf --id $ITEM_ID --field-id < iteration-field-id > --iteration-id < current-iteration-id >

CRITICAL: Every issue MUST be added to the project board. Issues not in the project board cannot be tracked for sprint progress. This is non-negotiable.

Best Practices

Use conventional commit style for titles : Prefix with type like feat(scope): , fix(scope): , docs: , etc.

Write thorough descriptions : Include:

Summary of what and why

Requirements or acceptance criteria

Technical notes or references to docs

Links to related issues (if any, but not parent issues—use sub-issues for that)

Apply appropriate labels : Always include at least:

Type label ( bug , enhancement , etc.)

Area label ( frontend , backend , etc.)

Severity label for bugs

Assign when ready : Only assign when someone is ready to work on it

Link to documentation : Reference relevant docs in the issue body (e.g., docs/​ACTIONS.md )

Issue Body Template

For consistency, use this structure for feature issues:

Summary

[ 1-2 sentence description of the feature ]

Requirements

• [ Requirement 1 ]
• [ Requirement 2 ]

Acceptance Criteria

• [ Criterion 1 ]
• [ Criterion 2 ]

Technical Notes

[ References to relevant documentation, architectural considerations ]

Out of Scope

[ What this issue explicitly does NOT cover ]