Spec Issues Create

Spec Issues Skill

Generate GitHub issue drafts from spec documents following the project's issue management framework.

When to Use

Use when you need to create GitHub issues from:

• Spec documents (./specs/)
• Any structured work breakdown ready for issue tracking

Workflow

Step 1: Validate Input Path

Parse path from command argument and verify:

# User provides path like:
# ./specs/active/my-feature
# ./specs/archive/nested-view-refactor

Validate directory exists and contains appropriate files.

Step 2: Detect Issue Type

Spec indicators:

• Has spec.md
• Has tasks.md
• Has context.md

Issue type detection:

1. Read spec.md frontmatter for issue_type field:

   ---
   issue_type: [Initiative|Feature|Task]
   created: [Date]
   status: Active
   ---
   

2. If issue_type present in frontmatter:

   • Skip type selection question
   • Use frontmatter value directly for template selection

3. If issue_type absent:

   • Fall back to current detection logic (spec overview analysis)
   • Consider asking user to classify

Template selection based on issue_type:

• Initiative → templates/initiative.md
• Feature → templates/feature.md
• Task → templates/task.md

Read appropriate files based on detected type.

Step 3: Create Issue Drafts Directory

mkdir -p "$SOURCE_DIR/drafts/issues"

Structure created:

./specs/archive/{spec-name}/drafts/issues/
├── initiative-{spec-name}.md
├── issue-001-{short-description}.md
├── issue-002-{short-description}.md
└── ...

Step 4: Generate Issue Draft Files

Create issue markdown files using templates:

Initiative file: initiative-{name}.md

• Use templates/initiative.md
• Map spec overview → initiative overview
• Map success criteria → acceptance criteria
• Include YAML frontmatter with metadata

Feature/Task files: issue-{NNN}-{description}.md

• Use templates/feature.md or templates/task.md
• Extract from spec phases or tasks
• Sequential numbering: 001, 002, 003
• Include YAML frontmatter

Key points:

• YAML frontmatter contains: title, labels, milestone, assignees
• Frontmatter serves as reference metadata
• Content extracted from spec documents

Step 5: Generate gh CLI Script

Create bash script using scripts/create-issue.sh:

• Parse YAML frontmatter from draft files
• Generate gh issue create commands
• Capture issue numbers for sub-issue linking
• Use gh sub-issue add for hierarchy
• Include helper function to extract YAML fields

Script structure:

#!/bin/bash
# Extract YAML → gh issue create → capture numbers → link sub-issues

Step 6: Provide Metadata Configuration Checklist

Include instructions for setting fields via GitHub web UI:

• Priority (Critical/High/Medium/Low)
• Status (Backlog/To Do/In Progress/etc.)
• Sprint/Iteration
• Complexity estimation
• Milestone/Release

Content Transformation

See mapping-guide.md for detailed rules on:

• Mapping spec content to issue hierarchy (Initiative → Feature → Task)
• Issue title patterns for each type
• Component label detection from file paths
• Priority and complexity mapping
• Cross-linking patterns

Quick summary:

• Specs: phases → Features, task breakdown → Tasks
• Titles follow verb-noun pattern, increasing specificity by level

Templates

• templates/initiative.md - Initiative issue template with YAML
• templates/feature.md - Feature issue template with YAML
• templates/task.md - Task issue template with YAML

Scripts

generate-issues.py: Automates draft generation from specs. Parses content, creates issue files with YAML frontmatter. create-issue.sh: Creates actual GitHub issues from drafts using gh CLI.

Requirement: Install gh sub-issue extension: gh extension install yahsan2/gh-sub-issue

Success Criteria

• Drafts directory created: {source}/drafts/issues/
• Initiative file with complete overview
• Feature/task files with proper templates
• gh CLI script with issue creation commands
• Metadata checklist provided

Integration

Workflow:

1. Complete spec
2. Invoke this skill with source path
3. Review generated draft files
4. Run gh CLI script to create issues
5. Set metadata via GitHub web UI

Related:

• Command: /spec.issues
• Tools: gh CLI, gh sub-issue extension