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:

Read spec.md frontmatter for issue_type field:

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

If issue_type present in frontmatter:
- Skip type selection question
- Use frontmatter value directly for template selection
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:

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

Related:

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