Issue Naming Conventions Skill

Apply consistent, traceable requirement IDs to GitHub issues using a canonical naming taxonomy. This skill ensures issues are standardized across repositories and enables full traceability from requirements to implementation.

⛔ MANDATORY PRE-FLIGHT PROTOCOL

STOP! Before ANY issue creation or ID assignment, you MUST complete this checklist:

┌─────────────────────────────────────────────────────────────────────────────┐
│  ISSUE ID ASSIGNMENT PRE-FLIGHT CHECKLIST (MANDATORY)                      │
├─────────────────────────────────────────────────────────────────────────────┤
│  □ Step 1: READ the taxonomy file                                          │
│            read_file .github/skills/issue-naming-conventions/references/   │
│                      issue-types.yml                                       │
│                                                                             │
│  □ Step 2: IDENTIFY the correct prefix for the issue type                  │
│            Match user intent to FR/BG/HF/TC/SC/PF/DC/IN                    │
│                                                                             │
│  □ Step 3: QUERY existing issues to find the highest ID                    │
│            gh issue list --search "PREFIX-" --state all --limit 500        │
│                                                                             │
│  □ Step 4: INCREMENT to next sequential number, zero-pad to 4 digits       │
│            If highest is FR-0042, next is FR-0043                          │
│                                                                             │
│  □ Step 5: VALIDATE the ID doesn't already exist before creating           │
│            gh issue list --search "PREFIX-NNNN" --state all                │
│                                                                             │
│  ⚠️  SKIPPING ANY STEP = PROTOCOL VIOLATION                                │
└─────────────────────────────────────────────────────────────────────────────┘

If you haven't queried existing issues for the highest ID, you CANNOT create an issue.

Critical Constraints

⚠️ ABSOLUTE RULE #1: You MUST NEVER create an issue without first querying existing issues to determine the next sequential ID.

⚠️ ABSOLUTE RULE #2: You MUST NEVER reuse an ID, even for closed or deleted issues. IDs are permanently allocated.

⚠️ ABSOLUTE RULE #3: You MUST NEVER invent new prefixes. Only use prefixes defined in issue-types.yml.

If a user requests an issue type that doesn't fit existing prefixes:

1. •Explain that no matching prefix exists
2. •Suggest the closest matching prefix from the taxonomy
3. •If truly no match, use TC (Technical Chore) as a fallback and note it in the issue

When to Use This Skill

• •User asks to create a new issue with proper ID
• •User asks to assign a requirement ID to work items
• •User asks to determine the next ID for a specific type
• •User asks about issue naming conventions or standards
• •User needs to ensure traceability across the codebase
• •User mentions FR, BG, HF, TC, SC, PF, DC, or IN prefixes
• •User asks to triage or categorize incoming work
• •User asks how to format an issue title

Issue Type Overview

All issues follow a [PREFIX-####] Title pattern. The taxonomy is defined in issue-types.yml.

Requirement Type Prefixes

CRITICAL: Changes to .github/ configuration files (agents, skills, instructions, prompts) should use TC-#### (Technical Chore) or FR-#### (Feature Request), NEVER DC-#### (Documentation). These files are configuration/tooling, not documentation.

ID Format Rules

• •Always 4-digit zero-padded: FR-0001, not FR-1
• •Range: 0001-9999 per prefix type
• •Permanent allocation: IDs are never reused, even for closed issues
• •Title format: [PREFIX-####] Descriptive Title
• •Max title length: 72 characters (including prefix)

Step-by-Step Workflows

Workflow 1: Create a New Issue with Proper ID

1. •

   Read the taxonomy: Load issue-types.yml to identify the correct prefix

2. •

   Match user intent: Determine which prefix fits (see type descriptions)

3. •

   Query existing issues: Find the highest ID for that prefix

   bash

   gh issue list --search "FR-" --state all --limit 500 --json title --jq '.[].title' | grep -oE 'FR-[0-9]+' | sort -t'-' -k2 -n | tail -1
   

4. •

   Increment the ID: If highest is FR-0042, next is FR-0043

5. •

   Validate uniqueness: Confirm the ID doesn't exist

   bash

   gh issue list --search "FR-0043" --state all
   

6. •

   Select template: Use the appropriate template from body-templates.md

7. •

   Create the issue: Apply proper title format and body template

Example Output:

Next available Feature Request ID: FR-0043

Issue title: [FR-0043] Add dark mode theme support

Using template: Feature Request (Full)
- Includes: Summary, User Story, Problem Statement, Proposed Solution, Acceptance Criteria

Workflow 2: Find Next Available ID

1. •

   Identify the prefix type from user request

2. •

   Execute the query:

   bash

   PREFIX="FR" && gh issue list --search "$PREFIX-" --state all --limit 500 --json title --jq '.[].title' | grep -oE "$PREFIX-[0-9]+" | sort -t'-' -k2 -n | tail -1 | awk -F'-' -v p="$PREFIX" '{printf "%s-%04d\n", p, $2+1}'
   

3. •

   If no issues exist with that prefix, start at 0001

4. •

   Report the result with confidence

Example:

Query: Find next Bug ID
Result: BG-0090 (current highest: BG-0089)

Workflow 3: Validate an Existing ID

1. •

   Parse the ID from user input

2. •

   Check format validity: Must match ^[A-Z]{2}-[0-9]{4}$

3. •

   Verify prefix exists in taxonomy

4. •

   Check issue existence:

   bash

   gh issue list --search "FR-0043" --state all --json number,title,state
   

5. •

   Report findings:

   • •If exists: Return issue details
   • •If not: Confirm ID is available for use

Workflow 4: Suggest Correct Prefix for Work Item

1. •Analyze the work description provided by user
2. •Match against type definitions in issue-types.yml
3. •Consider keywords: Each type has associated keywords
4. •Apply exclusion rules: Check "when_not_to_use" guidance
5. •Recommend the prefix with justification

Example:

Work: "The dashboard is loading slowly, taking 5+ seconds"
Analysis: Performance issue with measurable metric
Recommendation: PF (Performance)
Justification: Latency/speed issue, not a bug (functional), has measurable target

Quick Reference Commands

Find Next ID for Any Prefix

# Replace PREFIX with: FR, BG, HF, TC, SC, PF, DC, or IN
PREFIX="FR" && gh issue list --search "$PREFIX-" --state all --limit 500 --json title --jq '.[].title' | grep -oE "$PREFIX-[0-9]+" | sort -t'-' -k2 -n | tail -1 | awk -F'-' -v p="$PREFIX" '{printf "%s-%04d\n", p, $2+1}'

Check if ID Exists

gh issue list --search "FR-0043" --state all --json number,title,state

List All Issues with Prefix

gh issue list --search "BG-" --state all --limit 200 --json number,title,state

Get Highest ID for Each Prefix

for PREFIX in FR BG HF TC SC PF DC IN; do
  HIGHEST=$(gh issue list --search "$PREFIX-" --state all --limit 500 --json title --jq '.[].title' | grep -oE "$PREFIX-[0-9]+" | sort -t'-' -k2 -n | tail -1)
  echo "$PREFIX: ${HIGHEST:-$PREFIX-0000 (none)}"
done

Troubleshooting

References

• •Issue Type Definitions (YAML) — Canonical taxonomy
• •Issue Body Templates — Full and minimal templates for each type