Pattern-009: GitHub Issue Tracking Pattern

Status

Proven

Context

Software development projects require systematic tracking of work items, bugs, features, and process improvements. Without proper issue tracking, work becomes fragmented, progress is hard to measure, accountability suffers, and context is lost. The GitHub Issue Tracking Pattern addresses:

Pattern Description

The GitHub Issue Tracking Pattern provides systematic work item management through structured GitHub issues that serve as single sources of truth for development tasks. The pattern integrates issue tracking with development workflows, ensuring every significant work item has proper documentation, progress tracking, and evidence collection.

Implementation

Structure

# GitHub issue workflow integration
class GitHubIssueTracker:
    def __init__(self, github_agent: GitHubAgent):
        self.github_agent = github_agent

    async def create_work_item(self, title: str, description: str, labels: List[str]) -> int:
        """Create new tracked work item"""
        pass

    async def update_progress(self, issue_number: int, progress_update: str) -> None:
        """Update issue with progress evidence"""
        pass

    async def complete_work_item(self, issue_number: int, completion_evidence: str) -> None:
        """Mark work item complete with evidence"""
        pass

Example (GitHub CLI Integration)

# Before starting work - verify issue exists
gh issue view PM-XXX

# Create new issue with proper numbering
tail -5 docs/planning/pm-issues-status.csv  # Check next number
gh issue create --title "PM-171: Feature Implementation" \
    --body "Detailed description with acceptance criteria"

# During work - update issue description (not comments)
gh issue edit PM-171 --body "Updated description with progress checkboxes"

# Provide evidence links in issue updates
gh issue edit PM-171 --body "Progress update with evidence:
- [x] Phase 1 complete
- [ ] Phase 2 in progress
Evidence: commit abc123, deployment log xyz"

Example (Python Integration)

# Integration with development workflow
from services.integrations.github.github_agent import GitHubAgent

class ProjectWorkflow:
    def __init__(self):
        self.github_agent = GitHubAgent()

    async def start_work_item(self, issue_number: int):
        """Initialize work on tracked issue"""
        issue = await self.github_agent.get_issue_details(issue_number)
        logger.info(f"Starting work on {issue['title']}")
        return issue

    async def log_progress(self, issue_number: int, evidence: Dict[str, Any]):
        """Log progress with evidence to issue"""
        progress_update = self.format_progress_update(evidence)
        await self.github_agent.update_issue_description(
            issue_number,
            progress_update
        )

    def format_progress_update(self, evidence: Dict[str, Any]) -> str:
        """Format evidence for issue updates"""
        return f"""
        Progress Update:
        - Completed: {evidence.get('completed_tasks', [])}
        - Evidence: {evidence.get('evidence_links', [])}
        - Next: {evidence.get('next_steps', [])}
        """

Example (CSV Status Tracking)

# docs/planning/pm-issues-status.csv
issue_number,issue_title,status,last_updated,assignee
170,Pattern Catalog Consolidation,Open,2025-09-15,cursor-agent
171,Documentation Link Fixes,Closed,2025-09-15,cursor-agent
172,DDD Service Layer Implementation,In Progress,2025-09-15,code-agent

Usage Guidelines

Issue Creation Best Practices

Progress Tracking Best Practices

Integration Workflow Best Practices

Anti-Patterns to Avoid

Migration Notes (for consolidation from legacy systems)

Quality Assurance Checklist

Agent Coordination Notes

References

Last updated: September 15, 2025