Github issues standards

GitHub Issues Standards

This document defines the standardized structure for GitHub Issues in the Remind Tools project, ensuring consistent project management and clear hierarchical relationships.

Issue Hierarchy

PRD (Product Requirements Document)
├── EPIC #1 (Feature Group)
│   ├── TASK #1 (Implementation)
│   ├── TASK #2 (Implementation)
│   └── TASK #3 (Implementation)
├── EPIC #2 (Feature Group)
│   ├── TASK #4 (Implementation)
│   └── TASK #5 (Implementation)

Issue Types

1. PRD (Product Requirements Document)

Purpose: High-level strategic document defining product requirements and technical specifications.

Title Format: PRD #X: [Product/Feature Name] - [Brief Description]

Example: PRD #1: Trips by Remind Tools - Technical Foundation & Multi-Platform Deployment Pipeline

Required Labels:

• PRD (primary identifier)
• trips-app or money-app (application scope)
• Area labels: foundation, material-design-3, ci-cd, etc.
• Priority: high-priority or priority: high

Required Fields:

• Milestone: Phase-based (e.g., “Phase 1: Foundation”, “Phase 2: Core Features”)
• Assignee: Product Owner or Tech Lead
• Body Structure:
  • Executive Summary & Business Case
  • Problem Statement & Technical Requirements
  • Technical Solution Design
  • Success Metrics & KPIs
  • Implementation Strategy
  • Acceptance Criteria

Sub-issues: Contains 5-10 EPIC issues that implement the PRD requirements

---

2. EPIC (Feature Epic)

Purpose: Groups related implementation tasks for a major feature or system component.

Title Format: [EPIC] [Feature/Component Name]

Example: [EPIC] Project Foundation & Infrastructure

Required Labels:

• epic (primary identifier)
• Area labels: foundation, material-design-3, authentication, etc.
• trips-app or money-app (application scope)
• Priority: high-priority, medium-priority, or priority: high/medium

Required Fields:

• Milestone: Same as parent PRD
• Assignee: Tech Lead or Senior Developer
• Body Structure:
  • Overview & Epic Scope
  • Architecture Context
  • Implementation Tasks (checkbox list)
  • Technical Requirements
  • Acceptance Criteria
  • Dependencies & Blockers
  • Success Metrics
  • Definition of Done

Sub-issues: Contains 5-15 TASK issues that implement the epic

GitHub Dependencies:

• Blocked by: Previous epics that must complete first
• Blocking: Subsequent epics that depend on this one

---

3. TASK (Implementation Task)

Purpose: Specific, actionable implementation work that can be completed by a developer.

Title Format: [TASK] [Specific Implementation Description]

Example: [TASK] Implement ColorScheme.fromSeed() for Travel-Inspired Themes

Required Labels:

• task (primary identifier)
• Technical labels: database, supabase, material-design-3, ui-ux, etc.
• Area labels matching parent Epic

Required Fields:

• Milestone: Same as parent Epic
• Assignee: Specific developer responsible for implementation
• Body Structure:
  • Task Description
  • Parent Epic reference: “Issue #X - [Epic Name]”
  • Technical Requirements (with code examples)
  • Implementation Steps
  • Acceptance Criteria
  • Dependencies
  • Story Points (1, 2, 3, 5, 8, 13)
  • Labels list

GitHub Dependencies:

• Blocked by: Parent Epic and any prerequisite tasks
• Blocking: Tasks that depend on this implementation

---

Labeling System

Primary Type Labels (Required)

• PRD - Product Requirements Document
• epic - Feature Epic
• task - Implementation Task

Area/Domain Labels

• foundation - Project foundation and infrastructure
• material-design-3 - Material Design 3 implementation
• authentication - User authentication and authorization
• ci-cd - Continuous integration and deployment
• database - Database related work
• supabase - Supabase backend integration
• ui-ux - User interface and experience
• testing - Testing and quality assurance

Application Scope Labels

• trips-app - Trips by Remind Tools application
• money-app - Money by Remind Tools application

Priority Labels

• priority: critical - Critical priority, immediate response needed
• priority: high - High priority, needs immediate response
• priority: medium - Medium priority
• priority: low - Low priority
• high-priority - Alternative high priority label

Status Labels (Optional)

• status: blocked - Cannot proceed due to dependencies
• status: in progress - Currently being developed
• status: review needed - Ready for code review
• status: completed - Implementation finished

Technical Labels

• supabase - Supabase related work
• database - Database implementation
• cross-platform - Multi-platform considerations
• performance - Performance optimization
• accessibility - Accessibility compliance
• security - Security implementation

Milestone System

Phase-based Milestones

• Phase 1: Foundation - Project setup, architecture, core infrastructure
  • Due: 2025-10-15
  • Focus: Technical foundation, Material Design 3, Authentication basics
• Phase 2: Core Features - Authentication, trip management, core functionality
  • Due: 2025-12-15
  • Focus: User features, trip planning, core business logic

Milestone Assignment Rules

• PRD: Assigned to the phase it primarily targets
• EPIC: Same milestone as parent PRD
• TASK: Same milestone as parent Epic

Dependency Management

GitHub Dependencies Usage

Use GitHub’s built-in dependency tracking:

1. Epic → Epic Dependencies:

   • Epic A “blocks” Epic B if Epic B depends on Epic A
   • Epic B is “blocked by” Epic A

2. Epic → Task Dependencies:

   • Epic “blocks” all its child tasks
   • Tasks are “blocked by” their parent Epic

3. Task → Task Dependencies:

   • Task A “blocks” Task B if Task B needs Task A completed
   • Task B is “blocked by” Task A

Dependency Examples

Epic #8: Foundation
├── blocks: Epic #9 (Material Design 3)
├── blocks: Epic #10 (Authentication)
└── blocks: Epic #11 (Core UI)

Task #53: ColorScheme.fromSeed()
├── blocked by: Epic #9 (Material Design 3)  
├── blocks: Task #54 (Typography System)
└── blocks: Task #55 (Component Library)

Assignment Guidelines

PRD Assignment

• Product Owner: Strategic PRDs, business requirements
• Tech Lead: Technical architecture PRDs

Epic Assignment

• Tech Lead: Architecture epics, complex system design
• Senior Developer: Feature implementation epics
• Specialist: Domain-specific epics (CI/CD, Security, etc.)

Task Assignment

• Senior Developer: Complex implementation, architecture setup
• Developer: Standard feature implementation
• Junior Developer: Well-defined, smaller scope tasks

Body Templates

PRD Template

# PRD #X: [Title]

## 🎯 Executive Summary & Business Case
[Strategic context, market opportunity, competitive advantage]

## 🔍 Problem Statement & Technical Requirements  
[Current challenges, user needs, technical requirements]

## 🛠️ Technical Solution Design
[Architecture, technology stack, implementation approach]

## 📊 Technical Success Metrics & KPIs
[Measurable success criteria]

## 🚀 Implementation Strategy
[Phase breakdown, timeline, milestones]

## ✅ Acceptance Criteria
[Completion requirements]

Epic Template

# Epic: [Title]

## 🎯 Overview
[Epic purpose and scope]

## 📋 Epic Scope
[What's included/excluded]

## 🏗️ Architecture Context
[Technical context and design references]

## 📦 Implementation Tasks
- [ ] **[TASK]** Task description 1
- [ ] **[TASK]** Task description 2
- [ ] **[TASK]** Task description 3

## ✅ Acceptance Criteria
[Epic completion requirements]

## 🔗 Dependencies & Blockers
[Prerequisites and blocking issues]

## 📊 Success Metrics
[Performance targets and quality gates]

Task Template

## Task Description
[Specific implementation description]

## Parent Epic
Issue #X - [Epic Name]

## Technical Requirements
[Detailed technical specifications with code]

## Implementation Steps
1. Step 1
2. Step 2
3. Step 3

## Acceptance Criteria
- [ ] Requirement 1
- [ ] Requirement 2
- [ ] Requirement 3

## Dependencies
- Requires: Issue #X (Description)
- Blocks: Issue #Y (Description)

## Story Points: X

## Labels
`task`, `domain-label`, `technical-label`

Quality Guidelines

Title Guidelines

• Be Specific: Titles should clearly indicate the work scope
• Use Prefixes: Always include PRD #X:, [EPIC], or [TASK]
• Avoid Abbreviations: Use full words for clarity
• Action-Oriented: Tasks should start with action verbs

Body Guidelines

• Code Examples: Include relevant code samples for technical tasks
• Clear Steps: Break down complex work into clear steps
• Acceptance Criteria: Always include testable criteria
• Dependencies: Explicitly state all dependencies

Label Guidelines

• Minimum Labels: Each issue needs at least 3 labels (type, area, priority)
• Consistent Naming: Use existing labels, don’t create duplicates
• Descriptive: Labels should clearly indicate the work type and scope

Review Process

PRD Review

1. Business Review: Product Owner validates business requirements
2. Technical Review: Tech Lead validates technical approach
3. Stakeholder Review: Key stakeholders approve scope and timeline

Epic Review

1. Architecture Review: Tech Lead validates technical design
2. Task Breakdown: Ensure all necessary tasks are included
3. Dependency Review: Validate all dependencies are correct

Task Review

1. Technical Review: Senior Developer validates implementation approach
2. Acceptance Criteria Review: Ensure criteria are testable and complete
3. Assignment Review: Confirm appropriate developer assignment

Automation Rules

Auto-Labeling

• Issues with [EPIC] prefix automatically get epic label
• Issues with [TASK] prefix automatically get task label
• Issues with PRD #X: prefix automatically get PRD label

Auto-Assignment

• PRDs auto-assign to Product Owner role
• Epics auto-assign to Tech Lead role
• Tasks require manual assignment to specific developers

Auto-Milestones

• Child issues inherit parent milestone automatically
• Milestone changes propagate to child issues

This standards document ensures consistent, trackable, and well-organized project management across the entire Remind Tools development lifecycle.