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

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

undefined

**Bug Template**:
```markdown

**Feature Template**:
```markdown

undefined

undefined

**In Issue Body** (for documentation, not relationships):
```markdown

**Blocking Issues**:
```markdown

**Related Issues**:
```markdown

**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>`

undefined

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

**Step 2: Add to Project Board**
```bash

**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

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.

User: "Is this a good title: [BUG] Login fails"

You:
❌ Title has issues:
- Contains type prefix [BUG]

Suggested fix:
✅ "Fix login authentication failure"

The type is indicated by the `bug` label, not the title.

User: "What labels for 'Improve error messages for validation'"

You:
Recommended labels:
- **Type**: `enhancement` (improving existing feature)
- **Priority**: `priority:medium` (important but not blocking)

Required:
- **Scope**: `scope:claude-component-builder` (identifies component)

Optional:
- **Branch**: `branch:plugin/claude-component-builder` (if on feature branch)

User: "Help me write the body for 'Add tool name validation for hook matchers'"

You:

{
  "matcher": "git commit",
  "hooks": [...]
}

undefined

User: "Creating issue for 'Add environment variable validation'"

You:
I notice related issues in the hooks validation area:

**Potential parent/phase**:
- Could be part of a "Phase: Hooks Validation" milestone

**Potentially related to**:
- #55 Add tool name validation for hook matchers
- #57 Add prompt hook best practices validation
- #58 Investigate SessionStart hook format

Would you like to:
1. Create a phase milestone and group these?
2. Just link as related issues?
3. Keep standalone?

undefined

undefined

undefined

undefined

❌ [BUG] Login fails
❌ [FEATURE] Add dark mode
❌ [ENHANCEMENT] Improve performance

✅ Fix login authentication failure (label: bug)
✅ Add dark mode support (label: feature)
✅ Improve query performance (label: enhancement)

❌ Fix bug
❌ Update code
❌ Add feature

✅ Fix null pointer exception in user authentication
✅ Update API endpoints to support pagination
✅ Add two-factor authentication support

❌ Labels: bug, enhancement
✅ Labels: bug (choose primary type)

❌ Body: "Fix the login bug"

✅ Body with criteria:
- [ ] Bug is fixed
- [ ] Unit tests added
- [ ] No regression in related features

❌ WRONG - Task lists create "tracked" relationships, not parent-child:

**Why it matters**: Task list checkboxes only create "tracked by" links. True parent-child relationships require the GraphQL `addSubIssue` mutation, which enables:
- Progress tracking (X/Y completed)
- Hierarchy navigation in GitHub UI
- Sub-issue status aggregation

❌ WRONG - Creating issues without checking project context:
gh issue create --title "Add feature" --label "feature"

✅ CORRECT - Check env.json first, then add to project:

**Why it matters**: Issues not added to project boards lose visibility and don't appear in sprint planning or roadmaps.

❌ WRONG - Jumping straight to issue creation:
User: "Create issues for the new auth feature"
Claude: *immediately creates 5 issues*

✅ CORRECT - Ask clarifying questions first:
User: "Create issues for the new auth feature"
Claude: "Before I create these issues, let me confirm:
1. Should I add them to project #3?
2. Should the main feature issue be parent of the subtasks?
3. Should they be assigned to the v1.0 milestone?"

❌ WRONG - Ignoring that user has env.json open:
<ide_opened_file>env.json</ide_opened_file>
Claude: *doesn't read env.json*

✅ CORRECT - Read files the user has open:
<ide_opened_file>env.json</ide_opened_file>
Claude: *reads env.json to get project board, milestone, etc.*

❌ WRONG - Creating and moving on:
gh issue create ...
"Done! Created issue #67"

✅ CORRECT - Verify after creation:
gh issue create ...
gh issue view 67 --json labels,projectItems
python manage-relationships.py show-all --issue 67
"Created #67, added to project #3, linked as child of #50"

❌ WRONG - Only type label:
--label "feature"

✅ CORRECT - All three required labels:
--label "feature,priority:medium,scope:self-improvement"