[PROJECT] Redesign issue management methodology — epics, stories, sprints, tasks

[kristopherjturner]

Problem

The current approach to managing work items — issues, epics, milestones, tasks, sprints, etc. — is unclear and inconsistent. There is confusion about:

• What constitutes an epic vs. a story vs. a task vs. a sub-issue
• How to use GitHub milestones vs. GitHub Projects sprints (iteration fields)
• When to use [EPIC], [FEATURE], [DOCS], [BUG], [PROJECT] prefixes in issue titles
• How child/parent relationships work across repos in the same org-level project board
• How to plan and track sprint work vs. backlog vs. long-running epics
• How to use the existing project board fields (Status, Priority, Category, Effort, Solution, Sprint)

Goal

Design a simple, consistent, and scalable issue management methodology that the team can follow without confusion. The methodology should:

• Work within GitHub Issues + GitHub Projects (org-level board) — no external tools required
• Define clear hierarchy: Epic → Story → Task (and how each maps to GitHub constructs)
• Be lightweight enough that creating and tracking issues is not a burden
• Support sprint-based delivery planning using the existing Sprint iteration field on the project board
• Cover cross-repo scenarios (issues in different repos tracked on the same org project board)

Proposed Topics to Cover

1. Issue Hierarchy Definition

Level	GitHub Construct	When to Use
Epic	Issue with [EPIC] prefix + sub-issues	Large, multi-sprint body of work across one or more repos
Story	Issue with [FEATURE] / [DOCS] / [BUG] prefix	User-facing deliverable completable in one sprint
Task	Sub-issue checklist item OR standalone issue	A single focused unit of work within a story
Spike	Issue with [SPIKE] prefix	Research/investigation with a time-box

2. Project Board Fields — How to Use Them

• Status: Todo → In Progress → Done — move manually as work progresses
• Priority: P0 (blocking) → P1 (this sprint) → P2 (next sprint) → P3 (backlog)
• Effort: XS (<1hr), S (<half day), M (<1 day), L (<3 days), XL (1+ week)
• Sprint: Assign to a named sprint iteration — define sprint duration and naming convention
• Solution: Map every issue to the relevant solution area
• Category: Feature / Bug Fix / Documentation / Infrastructure / Refactor / Security

3. Sprint Process

• Define sprint naming convention (e.g., S01-2026-Q2, or date-based 2026-04-14)
• Define sprint planning: move P1 backlog items into the active sprint
• Define sprint review: close completed items, move incomplete to next sprint
• Define sprint retrospective: lightweight notes in repo-management/ or a GitHub Discussion

4. Cross-Repo Epics

• Epics can live in any repo but should be tracked on the org-level project board
• Use the GitHub sub-issues feature to link child issues (which may be in different repos) to the parent epic
• All issues (regardless of repo) should be added to the "Azure Local Solutions" project board

5. Label Strategy

Define a consistent label set applied across all repos:

• type/epic, type/feature, type/bug, type/docs, type/infra, type/refactor, type/spike
• priority/critical, priority/high, priority/medium, priority/low
• solution/<name> (mirror project board Solution field)

6. Issue Templates

Update .github/ISSUE_TEMPLATE/ files to match the new methodology:

• feature_request.md — Story template
• bug_report.md — Bug template
• Add epic.md — Epic template with sub-issue checklist section
• Add spike.md — Research spike template

Deliverables

• Written methodology document in azurelocal.github.io/repo-management/ or azurelocal.github.io/standards/
• Sprint naming convention and duration defined
• GitHub issue templates updated across all repos to match
• Project board Sprint iteration field configured with named sprints
• Team walkthrough: brief Markdown guide on how the org uses issues, epics, milestones, sprints, and tasks

References

• Current project board: https://github.com/orgs/AzureLocal/projects/3
• Current issue templates: .github/ISSUE_TEMPLATE/ in each repo

Context

Recreated from AzureLocal/demo-repository#1 because demo-repository is a private test-config repository and should not carry org governance or project-management issues.