Systematic Issue Management Rules

Overview

This document establishes systematic rules for GitHub issue management to ensure consistent tracking, accurate status reporting, and proper completion documentation. These rules are based on the August 5, 2025 systematic GitHub reconciliation deployment.

Core Principles

1. URL Precision

• All issue references must include exact GitHub URLs
• Format: https://github.com/mediajunkie/piper-morgan-product/issues/{number}
• No generic references like “PM-034” without URLs

2. Status Accuracy

• Issues must reflect actual implementation status
• Completion evidence must be documented
• Superseded issues must be properly closed with references

3. Documentation Synchronization

• Backlog and roadmap must match GitHub issue status
• All documentation must include exact GitHub URLs
• Completion dates and achievements must be recorded

Issue Lifecycle Rules

Issue Creation

**Required Fields**:

- Title: Clear, descriptive issue name
- Description: Comprehensive scope and acceptance criteria
- Labels: Appropriate categorization (enhancement, bug, etc.)
- Assignees: Clear ownership assignment
- Milestone: Strategic placement in roadmap
- Estimate: Story points with rationale

Issue Implementation

**Required Documentation**:

- Implementation timeline with start/end dates
- Technical achievements with code volume
- Performance validation with empirical evidence
- Integration points and dependencies
- Test coverage and quality metrics

Issue Completion

**Required Closure Evidence**:

- All acceptance criteria met with checkmarks
- Performance validation with actual metrics
- Integration testing results
- Documentation completeness
- GitHub URL for future reference

Supersession Rules

When to Supersede

• Original scope significantly expanded
• Technical approach fundamentally changed
• Implementation exceeds original requirements
• New dependencies require scope adjustment

Supersession Documentation

**Required in Original Issue**:

- Superseding issue number and URL
- Completion evidence from enhanced implementation
- Scope expansion explanation
- Technical achievement summary
- Resolution: SUPERSEDED with reference

Example Supersession

SUPERSEDED BY #80 PM-034: LLM-Based Intent Classification with Knowledge Graph Context

This issue has been superseded by the enhanced PM-034 implementation that incorporates Knowledge Graph context integration.

## Completion Evidence

- Superseding Issue: #80 PM-034 LLM Classification with Knowledge Graph Context
- Status: Original PM-034 scope expanded with PM-040 Knowledge Graph integration
- Implementation: Multi-stage pipeline with context enrichment completed August 5, 2025
- Validation: Empirical performance validation with 28,455 req/s throughput

Resolution: SUPERSEDED - Enhanced implementation complete in #80

Documentation Synchronization Rules

Backlog Updates

**Required for Completed Issues**:

- Status: ✅ COMPLETE with completion date
- GitHub Issue: Exact URL
- Key Achievements: Technical accomplishments
- Performance Metrics: Empirical validation results
- Supersession Notes: If applicable

Roadmap Updates

**Required for All Issues**:

- Current status with completion dates
- GitHub issue URLs for all references
- Dependencies and integration points
- Strategic impact and business value

URL Precision Template

Issue Reference Format

**GitHub Issue**: https://github.com/mediajunkie/piper-morgan-product/issues/{number}

**Example**:
PM-040: Advanced Knowledge Graph Implementation
**GitHub Issue**: https://github.com/mediajunkie/piper-morgan-product/issues/79

Documentation Update Template

### ✅ PM-040: Advanced Knowledge Graph Implementation - COMPLETE (August 4, 2025)

**Story**: As an organization, we want cross-project learning and pattern recognition through knowledge graphs
**Description**: Implemented comprehensive knowledge graph system with metadata-based semantic understanding
**Estimate**: 55+ points | **Status**: ✅ COMPLETE | **Delivered**: All 3 phases in single day
**GitHub Issue**: https://github.com/mediajunkie/piper-morgan-product/issues/79

**Key Achievements**:

- ✅ Complete database schema with KnowledgeNode/KnowledgeEdge models
- ✅ KnowledgeGraphRepository with 13 specialized graph operations
- ✅ KnowledgeGraphService with 20+ business logic methods
- ✅ SemanticIndexingService with validated metadata embeddings
- ✅ **Hypothesis Validated**: Metadata-based embeddings achieve 0.803 similarity clustering
- ✅ Privacy-first design (metadata-only analysis)
- ✅ pgvector integration ready

**Technical Impact**: Enables cross-project pattern recognition, intelligent similarity search, and privacy-preserving analytics

**Supersedes**: PM-030 (closed) https://github.com/mediajunkie/piper-morgan-product/issues/59

Reconciliation Process

Monthly Reconciliation

1. Issue Status Audit: Verify all issues reflect actual status
2. Documentation Sync: Update backlog and roadmap with URLs
3. Supersession Review: Close superseded issues with evidence
4. Completion Validation: Ensure all completed issues have evidence

Quarterly Deep Clean

1. URL Precision: Add missing GitHub URLs to all documentation
2. Status Accuracy: Verify completion dates and achievements
3. Dependency Mapping: Update integration points and relationships
4. Strategic Alignment: Ensure roadmap reflects current priorities

Validation Checklist

Issue Creation

• Clear title and description
• Appropriate labels and assignees
• Realistic estimate with rationale
• Dependencies identified
• Acceptance criteria defined

Issue Implementation

• Timeline documented
• Technical achievements recorded
• Performance validation completed
• Integration points tested
• Documentation updated

Issue Completion

• All acceptance criteria met
• Performance targets achieved
• GitHub URL included in documentation
• Completion evidence documented
• Supersession handled if applicable

Documentation Sync

• Backlog reflects current status
• Roadmap includes GitHub URLs
• Completion dates accurate
• Supersession references correct
• Performance metrics documented

August 5, 2025 Reconciliation Results

Issues Reconciled

• ✅ PM-030 (#59): Superseded by PM-040 (#79) - Advanced Knowledge Graph
• ✅ PM-034 (#61): Superseded by PM-034 enhanced (#80) - LLM Classification with KG Context
• ✅ PM-040 (#79): Complete - All phases delivered in single day
• ✅ PM-034 enhanced (#80): Complete - Multi-stage pipeline with empirical validation

Documentation Updated

• ✅ Backlog: All issues include exact GitHub URLs
• ✅ Roadmap: Status reflects actual completion
• ✅ Supersession: Proper closure with evidence
• ✅ Performance: Empirical validation documented

Systematic Rules Established

• ✅ URL precision requirement
• ✅ Status accuracy validation
• ✅ Supersession documentation
• ✅ Completion evidence standards

Future Enforcement

Automated Checks

• GitHub issue URLs in all documentation
• Status consistency between GitHub and documentation
• Completion evidence for all closed issues
• Supersession references for replaced issues

Manual Reviews

• Monthly reconciliation process
• Quarterly deep clean
• Pre-release documentation audit
• Strategic planning alignment

Success Metrics

Issue Management Quality

• URL Precision: 100% of issue references include GitHub URLs
• Status Accuracy: 100% match between GitHub and documentation
• Completion Evidence: All closed issues have documented achievements
• Supersession Handling: Proper closure with references

Documentation Quality

• Synchronization: Backlog and roadmap match GitHub status
• Completeness: All issues have proper documentation
• Accuracy: Performance metrics and achievements documented
• Accessibility: Clear references for future development

Document Status: ✅ ACTIVE Rules Established: ✅ AUGUST 5, 2025 Enforcement: ✅ SYSTEMATIC Validation: ✅ COMPREHENSIVE