| name | github-issue-creation |
| description | GitHub issue creation best practices including label verification, format standards, and systemic issue detection. Prevents duplicate work and ensures proper categorization. |
| allowed-tools | Read, Bash |
GitHub Issue Creation
ISSUE_MASTERY::[LABEL_VERIFICATION+FORMAT_STANDARDS+SYSTEMIC_DETECTION]→CLEAR_BACKLOG
LABEL_VERIFICATION
BEFORE_CREATE::[
MANDATORY::check_existing_labels[gh_label_list_OR_GitHub_UI],
COMMAND::"gh label list",
VERIFY::label_exists_before_applying[prevents_typos+maintains_taxonomy],
COMMON_LABELS::[bug, enhancement, documentation, technical-debt, security, performance]
]
LABEL_SELECTION::[
SINGLE_TYPE::choose_one[bug|enhancement|chore],
OPTIONAL_MODIFIERS::[priority-high, needs-investigation, cross-app],
ANTI_PATTERN::NEVER[create_new_labels_without_discussion, apply_nonexistent_labels]
]
FORMAT_STANDARDS
TITLE::[
PATTERN::"[Component] Brief description",
EXAMPLES::["[Auth] RLS policy blocks valid users", "[CI] Flaky test in scenes-web", "[Docs] Missing API examples"],
RULES::[descriptive≠vague, component_prefix_when_relevant, <80_chars]
]
BODY_STRUCTURE::[
CONTEXT::"What's happening? Why is this important?",
EXPECTED::"What should happen instead?",
CURRENT::"What actually happens?",
REPRODUCTION::"Steps to reproduce (if bug)",
OPTIONAL::[screenshots, logs, related_issues]
]
TEMPLATE_EXAMPLE::
"""
**Context:**
Users with valid session tokens are getting 403 errors when accessing script comments.
**Expected:**
Authenticated users should be able to read comments on their own scripts.
**Current:**
403 Forbidden error from Supabase RLS policy.
**Reproduction:**
1. Login as test user
2. Navigate to script with comments
3. Observe error in console
"""
SYSTEMIC_DETECTION
CREATE_ISSUE_WHEN::[
SYSTEMIC::cannot_fix_immediately[requires_prioritization],
CROSS_APP::coordination_required[multiple_apps_affected],
TECHNICAL_DEBT::refactoring_needed[paydown_strategy],
DISCOVERED_BUGS::deprioritized[fix_later],
SECURITY_PERFORMANCE::investigation_required[deep_analysis],
RECURRING::pattern_observed[happens_across_apps]
]
SKIP_ISSUE_WHEN::[
IMMEDIATE_FIX::resolved_current_session[just_fix_it],
MINOR_DETAIL::solved_during_feature[no_tracking_needed],
TEMPORARY::scaffolding[documented_in_.coord],
ALREADY_TRACKED::[TodoWrite_sufficient, PROJECT_CHECKLIST_covers]
]
COORDINATION_PHILOSOPHY::[
GIT_ISSUES::long_term_backlog+prioritization+cross_session_visibility,
COORD_DOCS::binding_decisions+system_state+phase_artifacts,
TODOWRITE::current_session_task_execution
]
CREATION_WORKFLOW
STEP_BY_STEP::[
1→verify_labels::"gh label list"→choose_existing,
2→check_duplicates::"gh issue list --search 'keyword'"→avoid_redundancy,
3→draft_title::"[Component] Clear description",
4→write_body::context→expected→current→reproduction,
5→apply_labels::verified_labels_only,
6→create::"gh issue create --title '...' --body '...' --label '...'"
]
COMMAND_EXAMPLES::[
list_labels::"gh label list",
search_existing::"gh issue list --search 'RLS policy'",
create_issue::"gh issue create --title '[Auth] RLS circular dependency' --body '$(cat issue.md)' --label 'bug,priority-high'",
interactive::"gh issue create" # Opens editor for body
]
ANTI_PATTERNS
AVOID::[
SKIP_LABEL_CHECK::applying_nonexistent_labels→orphaned_issues,
VAGUE_TITLES::"fix stuff"→unsearchable,
NO_CONTEXT::"doesn't work"→cannot_reproduce,
PREMATURE_ISSUES::tracking_trivial_tasks→noise,
DUPLICATE_TRACKING::issue+TodoWrite+PROJECT_CHECKLIST→confusion
]
QUALITY_GATE::[
BEFORE_CREATE::ask["Is this systemic?", "Can I fix it now?", "Do labels exist?"],
LABEL_VERIFIED::command_run_confirms_label_exists,
FORMAT_FOLLOWED::title_pattern+body_structure,
NO_DUPLICATES::search_performed_first
]
INTEGRATION
CONSULTED_BY::[implementation-lead, holistic-orchestrator, quality-observer, principal-engineer]
TRIGGERS::[
SYSTEMIC_ISSUE_DETECTED,
CROSS_APP_CONCERN_IDENTIFIED,
TECHNICAL_DEBT_DISCOVERED,
RECURRING_PATTERN_OBSERVED
]
AUTHORITY::ADVISORY[suggest_issue_creation_when_appropriate≠force]
WISDOM
CORE_TRUTH::"Labels organize, format clarifies, systemic detection prevents noise"
REMEMBER::[
"Always verify labels exist before creating issue",
"Fix immediately if possible → Skip issue creation",
"Context+Expected+Current = Actionable issue",
"Search before creating → Prevent duplicates",
"Systemic issues deserve tracking → Trivial tasks don't"
]
