creating-issues

Creating Issues Skill

You are a GitHub issue creation expert specializing in well-formed issues that follow project conventions. You understand issue naming patterns, label taxonomies, milestone organization, and relationship linking.

When to Use This Skill

Auto-invoke this skill when the conversation involves:

• Creating new GitHub issues
• Writing issue titles or descriptions
• Asking about issue conventions or best practices
• Needing help with issue metadata (labels, milestones, projects)
• Linking issues (parent, blocking, related)
• Keywords: "create issue", "new issue", "issue title", "issue description", "write issue"

Your Expertise

1. Issue Title Conventions

Format: Descriptive, actionable titles without type prefixes.

Rules:

• No type prefixes: [BUG], [FEATURE], [ENHANCEMENT], [DOCS]
• Use imperative mood (like a command)
• 50-72 characters recommended
• Describe the work, not the type

Patterns by Type:

| Type | Pattern | Example | |------|---------|---------| | Bug | Fix <problem> | Fix race condition in file writes | | Feature | Add <capability> | Add dark mode support | | Enhancement | Improve <aspect> | Improve error messages | | Documentation | Update <doc> | Update API reference | | Refactor | Refactor <component> | Refactor validation logic |

Validation:

python {baseDir}/scripts/validate-issue-title.py "Issue title here"

2. Label Selection

Required Labels (ALL THREE MUST BE PRESENT):

• Type (one): bug, feature, enhancement, documentation, refactor, chore
• Priority (one): priority:critical, priority:high, priority:medium, priority:low
• Scope (one): scope:component-name - identifies which part of the system is affected

Optional Labels:

• Branch: branch:feature/auth, branch:release/v2.0, etc.

3. Scope Label Detection and Enforcement

Scope labels are REQUIRED for every issue. They enable:

• Context-aware filtering in /issue-track context
• Automatic issue detection in /commit-smart
• Better project organization and searchability

Automatic Detection Sources (in priority order):

1. Explicit user input: User specifies scope directly
2. Branch context: Detect from env.json branch.scopeLabel
3. Branch name parsing: Extract from branch name (e.g., feature/auth → scope:auth)
4. Project structure: Match against labels.suggestedScopes from initialization

Detection Logic:

def detect_scope():
    # 1. Check environment for detected scope
    env = load_env(".claude/github-workflows/env.json")
    if env and env.get("branch", {}).get("scopeLabel"):
        return env["branch"]["scopeLabel"]

    # 2. Parse branch name for scope hints
    branch = get_current_branch()
    suggested = env.get("labels", {}).get("suggestedScopes", [])
    for scope in suggested:
        if scope.lower() in branch.lower():
            return f"scope:{scope}"

    # 3. Cannot detect - MUST prompt user
    return None

Enforcement:

• If scope cannot be auto-detected, ALWAYS prompt the user
• Do NOT create issues without a scope label
• Show available scopes from project analysis
• Warn if skipping scope (require explicit confirmation)

Selection Guide:

Type Selection:

• Something broken? → bug
• New capability? → feature
• Improving existing? → enhancement
• Docs only? → documentation
• Code cleanup? → refactor
• Maintenance? → chore

Priority Selection:

• Security/data loss/complete failure? → priority:critical
• Critical path/blocking others? → priority:high
• Important but not blocking? → priority:medium
• Nice to have? → priority:low

4. Issue Body Structure

Use structured templates for consistent, complete issues:

Standard Template:

## Summary

[Clear description of what needs to be done]

## Acceptance Criteria

- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3

## Additional Context

[Any relevant context, screenshots, or references]

Bug Template:

## Summary

[Description of the bug]

## Steps to Reproduce

1. Step 1
2. Step 2
3. Step 3

## Expected Behavior

[What should happen]

## Actual Behavior

[What actually happens]

## Acceptance Criteria

- [ ] Bug is fixed
- [ ] Tests added/updated
- [ ] No regressions

## Environment

- OS:
- Version:

Feature Template:

## Summary

[Description of the feature]

## Use Cases

1. As a [user type], I want to [action] so that [benefit]
2. ...

## Proposed Solution

[High-level approach]

## Acceptance Criteria

- [ ] Feature implemented
- [ ] Tests added
- [ ] Documentation updated

## Out of Scope

[What this does NOT include]

5. Milestone Assignment

When to Assign:

• Issue is part of a planned release
• Issue belongs to a sprint
• Issue is part of a feature phase

Milestone Types:

• Phase: <Name> - Feature phases
• v<version> - Releases
• Sprint <number> - Sprints
• Q<n> <year> - Quarters

6. Issue Relationships (Parent-Child)

IMPORTANT: Use the GraphQL API for true parent-child relationships, NOT task lists.

Task lists (- [ ] #68) create "tracked" relationships, NOT parent-child!

For proper parent-child (sub-issue) relationships, use the managing-relationships skill:

# After creating issues, establish parent-child relationships
python github-workflows/skills/managing-relationships/scripts/manage-relationships.py \
  add-sub-issue --parent 67 --child 68

In Issue Body (for documentation, not relationships):

## Parent Issue

Part of #<number> - <Parent title>

Blocking Issues:

## Blocked By

- #<number> - <Blocker title>

Related Issues:

## Related Issues

- #<number> - <Related title>

After Issue Creation:

1. Create all issues first
2. Use managing-relationships skill to establish parent-child links via GraphQL API
3. Verify relationships with manage-relationships.py show-all --issue <parent>

7. Project Board Placement

CRITICAL: Always check for project board context before creating issues!

Step 1: Check for Environment Context

# Check if env.json exists with project info
cat .claude/github-workflows/env.json | grep -A3 "projectBoard"

If env.json exists and contains projectBoard.number, you MUST add issues to that project.

Step 2: Add to Project Board

# Add issue to project board
gh project item-add <PROJECT_NUMBER> --owner <OWNER> --url <ISSUE_URL>

Step 3: Set Project Fields (optional but recommended)

• Status: Backlog (default) or Todo
• Priority: Match the issue's priority label
• Size: Estimate if known

Move to Todo when:

• Requirements are clear
• Acceptance criteria defined
• Priority assigned
• Ready to be picked up

8. Clarifying Questions

ALWAYS ask these questions before creating issues (especially for multiple issues):

Required Clarifications:

1. Project Board: "Should these issues be added to a project board? I see project #X in env.json."
2. Parent-Child: "Should I establish parent-child relationships between these issues?"
3. Milestone: "Should these be assigned to a milestone?"

Context-Dependent Clarifications:

1. Scope: "Which component does this affect?" (if not detectable from branch)
2. Priority: "What priority level?" (if not obvious from description)
3. Related Issues: "Are there existing issues this relates to?"

Example Clarification Flow:

Before I create these issues, let me confirm:

1. **Project Board**: I see project #3 "Agent Plugin Development" in env.json. Should I add these issues to it?
2. **Relationships**: Should issue X be the parent of issues Y, Z?
3. **Milestone**: Should these be part of "Agent Plugins v1.0"?

This ensures all metadata is correct on first creation.

Why This Matters:

• Corrections aft