GitHub Issues Rules

Guidelines for managing GitHub issues and their relationship with the project plan.

File: github-issues-rules.mdc

Purpose

The GitHub Issues Rules establish standards for creating, managing, and organizing GitHub issues to ensure consistency, traceability, and alignment with the project plan.

Key Principles

  • Clear Structure: Well-defined issue organization

  • Complete Information: Comprehensive issue content requirements

  • Consistent Workflow: Standard issue management processes

  • Plan Integration: Connection between issues and project planning

  • Effective Prioritization: Systematic approach to issue importance

  • Progress Tracking: Clear status indication and milestone mapping

Detailed Contents

Issue Creation Standards

Guidelines for creating new issues:

  • Required issue template usage

  • Minimum information requirements

  • Reproduction steps format for bugs

  • Definition criteria for features

  • Required fields completion

  • Initial labeling requirements

Issue Organization

Standards for issue categorization:

  • Label taxonomy and color coding

  • Epic/feature/task hierarchy

  • Milestone assignment criteria

  • Project board organization

  • Issue relationship documentation

  • Status tracking methodology

Issue Management Workflow

Process for handling issues through lifecycle:

  • Triage process requirements

  • Assignment guidelines

  • Status update frequency

  • Comment and discussion standards

  • Resolution and closure criteria

  • Reopening policies

Quality Standards

Requirements for issue quality:

  • Acceptance criteria definition

  • Completeness checklist

  • Testability requirements

  • Dependencies documentation

  • Edge case consideration

  • Technical debt tracking

Priority Classification

Guidelines for prioritization:

  • Priority level definitions

  • Impact assessment criteria

  • Effort estimation approach

  • Priority change documentation

  • Emergency issue handling

  • Backlog grooming process

Project Plan Integration

Standards for connecting issues to planning:

  • Sprint/iteration mapping

  • Roadmap alignment documentation

  • Feature flag relationship

  • Release planning connection

  • Project metric tracking

  • Stakeholder visibility requirements

Issue Templates

Requirements for issue templates:

  • Bug report template structure

  • Feature request template elements

  • Documentation issue format

  • Security vulnerability report format

  • Technical debt template

  • Epic/user story structure

Issue Linking

Guidelines for issue relationships:

  • Parent-child relationship notation

  • Dependency documentation format

  • Blocked/blocking notation

  • Related issue identification

  • External reference linking

  • Cross-repository issue connections

Automation Rules

Standards for issue automation:

  • Auto-assignment configuration

  • Automated labeling requirements

  • Status transition automation

  • Notification requirements

  • Activity tracking automation

  • Stale issue handling

Reporting Standards

Guidelines for issue reporting:

  • Required status reports

  • Issue velocity tracking

  • Burndown/burnup requirements

  • Backlog health metrics

  • Issue closure rate tracking

  • Issue distribution analysis

Search and Filter Organization

Standards for finding issues:

  • Saved search configurations

  • Filter naming conventions

  • View sharing requirements

  • Search term standardization

  • Query complexity guidelines

  • Cross-project searching

External Integration

Requirements for connecting to external tools:

  • Project management tool integration

  • Communication platform connections

  • Documentation system linking

  • Customer support ticket relationships

  • CI/CD pipeline connections

  • Analytics platform integration

Rationale

The GitHub Issues Rules provide several key benefits:

  1. Visibility: Clear overview of all work items and their status

  2. Traceability: Complete history of requirements and decisions

  3. Planning: Effective resource allocation and timeline management

  4. Quality: Consistent approach to capturing all necessary information

  5. Efficiency: Streamlined workflow with reduced administrative overhead