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