Create GitHub Issue

Create comprehensive GitHub issues using gh issue create by dynamically discovering and adhering to the repository’s official issue templates.

Workflow

1. Discover and Select Template

CRITICAL: You must use the repository’s official templates. Do not assume the structure.

1. List available templates:

   ls .github/ISSUE_TEMPLATE/
   

2. Select the most appropriate template based on the issue type (e.g., bug_report.yml, feature_request.yml).
3. Read the selected template to understand its required fields, structure, and any title prefixes or default labels.

   cat .github/ISSUE_TEMPLATE/<selected_template>.yml
   

2. Gather Context

Gather relevant information to fulfill the template requirements:

# Check current git status for context
git status

# View recent commits if related to codebase changes
git log --oneline -10

# Check if related issues exist
gh issue list --search "keyword" --limit 10

3. Generate Markdown Body

MANDATORY: Structure the issue body exactly as defined in the selected YAML template without exception.

1. Map YAML fields to Markdown: Convert each field in the template (typically found under body:) into a Markdown section.
2. Use Headers: Use the label or id from the YAML field as an H2 header (e.g., ## Bug Description).
3. Respect Validation: Ensure all fields marked as required: true in the YAML are populated with meaningful content.
4. Format Correctly: Use code blocks (e.g., ```shell, ```yaml) for logs and configurations as suggested by the template’s render attribute.

4. Choose Labels

Select labels by inspecting .github/labels.json.

• Primary Label: Always include a type: label that matches the issue type.
• Additional Labels: Add relevant state:, work:, or priority: labels if they exist in the configuration.
• Constraint: Only use labels defined in .github/labels.json.

5. Create Title

Follow the template’s title field if it provides a prefix (e.g., "[Bug]: ").

• Be concise: Keep under 70 characters.
• Use imperative mood: “Fix authentication timeout” instead of “Authentication is timing out”.
• Start with action verb: Fix, Add, Improve, Update, Refactor.

6. Execute Issue Creation

Step 1: Write body to temp file Use the write tool to create .forge/FORGE_ISSUE_BODY.md with the structured Markdown content.

Step 2: Create issue

gh issue create \
  --title "[Prefix]: Descriptive Title" \
  --body-file .forge/FORGE_ISSUE_BODY.md \
  --label "type: <type>, work: <complexity>"

Optional flags:

• --assignee "username"
• --milestone "name"
• --draft (For proposals or research)

7. Finalize

Provide the user with the generated issue URL and a brief summary of the created issue.

Guidelines

• No Exceptions: You must follow the discovered template’s structure exactly. If a template asks for “Steps to Reproduce”, you must provide them.
• Dynamic Discovery: Always read the files in .github/ISSUE_TEMPLATE/ and .github/labels.json first. Never rely on hardcoded knowledge of templates or labels as they change frequently.
• Cleanliness: Ensure no placeholder text (like “Describe the bug…”) remains in the final body.
• Contextual Awareness: If the user provides logs or code snippets, ensure they are placed in the correct sections of the template.

Notes

• Single Source of Truth: The files in .github/ are the authoritative reference for issue structure and categorization.
• Tooling: Use gh CLI directly. It is pre-authenticated and ready for use.
• Automation: Do not ask for confirmation before creating the issue if the user’s intent is clear.