ADR 016 — GitHub Issues Quality Standards for XO Data Ops¶
Status¶
Accepted
Context¶
The XO Data Ops team (BI + data engineering) began using GitHub Issues as its primary project management tool to align with other departments at XtendOps that already use it. The adjacent [Product] team (project #6) had already established a mature issue workflow — with defined issue types, label taxonomy, quality gates, custom project fields, and sprint rhythm — through months of iterative refinement.
Without a documented standard for the XO Data Ops project (#15), issues would vary widely in quality: missing acceptance criteria, vague titles, no priority, no effort estimates. This creates friction at sprint planning (can't pull in unrefined issues), ambiguity during execution (no clear closure criteria), and poor traceability after the fact.
The team needed a single reference document that: 1. Defines what each issue type means and when to use it 2. Specifies the quality bar an issue must meet before work starts 3. Establishes consistent labeling, field usage, branch naming, and PR conventions
Decision¶
Adopt the [Product] team's issue quality standards — including issue types, label taxonomy, "Definition of Refined" quality gate, and lifecycle stages — for the XO Data Ops GitHub project (#15), with the following specifics:
Issue types: Epic, Feature, Bug, Spike, Decision, Chore, Docs (and ELT Pipeline as a specialized Feature subtype)
Title convention: [Type] Imperative verb + brief description
Label taxonomy (3 tiers):
- Type labels: type: feature, type: bug, type: spike, type: chore, type: docs
- Priority labels: P1 - Critical, P2 - High, P3 - Normal, P4 - Low
- Area labels: area: snowflake, area: airflow, area: elt, area: xoos, area: shared-utils, area: ops
- Status labels: status: blocked, status: needs-decision
Custom project fields: Priority, Area, Phase, Effort (XS/S/M/L/XL), Iteration (biweekly)
Definition of Refined — an issue must have ALL before work starts:
- Title with [Type] prefix and imperative verb
- type: label set
- area: label set
- Priority label set
- Effort field set
- Acceptance criteria as checkbox list in body
Issue lifecycle: Backlog → Refined → In Progress → In Review → Done
Branch naming: <type>/<issue-number>-<short-description>
PR requirements: Fixes #N in body, use PR template, 1 review before merge
Sprint cadence: Biweekly, with Monday planning, Thursday blocker check, Friday close
The full standards are documented in docs/guides/github-issues-quality-standards.md.
Consequences¶
Gets easier: - Sprint planning is faster — Refined issues are immediately pullable - Closure is unambiguous — acceptance criteria define "done" - Cross-team collaboration is smoother — [Product] team and XO Data Ops use the same vocabulary - Traceability is automatic — branch names include issue numbers, PRs auto-close issues on merge
Gets harder: - Creating a quick issue takes more thought upfront — templates require filling in Goal, Acceptance Criteria, Context - Backlog grooming is now a required activity — unrefined issues block sprint planning
What we give up:
- Informal issue creation (no template, vague titles) — everything must follow the standard
- Marking issues done by comment — closure requires a PR with Fixes #N
Options Considered¶
Option 1: Adopt [Product] team's standards as-is (chosen)¶
Leverage the existing, proven workflow without reinventing it. Low effort, high consistency across the org.
Option 2: Build a custom standard from scratch¶
Design a workflow specific to data/BI work. Would take significant time and risk divergence from org-wide norms. Rejected — the [Product] team's standards already cover all our issue types including ELT pipelines.
Option 3: Use no formal standard — ad-hoc issues¶
Continue with informal issues. Rejected — this directly caused the sprint planning friction that prompted this ADR.
Amendment — 2026-03-19: Label Taxonomy Simplification¶
Status: Accepted
Change: Simplified the label taxonomy and project field structure to eliminate duplication between labels and project fields.
Before: 16 labels (5 type, 4 priority, 6 area, 2 status) + Area project field + no Domain field.
After: 4 area labels only. Type handled by native GitHub Issue Types. Priority handled by Priority project field only (no priority labels). Status labels removed (use board Status column + comments). Domain added as a project field.
Rationale: Labels travel with the issue everywhere (CI, PR sidebar, notifications) — they should carry information that matters outside the project board (area for CI enforcement, type for quick scanning). Priority and status are planning metadata that only matters on the board. Removing the duplication reduces noise and makes the label list immediately legible.
Migration performed: 22 label renames (area: snowflake/xoos → snowflake/xoos), 2 new labels created (pipelines, platform), 20 issues migrated to new area labels, 31 issues had Priority project field set before priority labels were deleted, 6 retired labels deleted (area: airflow, elt, ops, shared-utils, status: blocked, needs-decision).
Amendment — 2026-03-19: Issue Hierarchy & Template Overhaul¶
Status: Accepted
Changes:
1. [Decision] type dropped — folded into [Spike] (a spike that produces an ADR)
2. Issue hierarchy formalized: Epic → Feature → Task/Bug/Docs, with standalone variants
3. Native Task type expanded: covers both generic implementation work and time-boxed research
4. Docs companion rule: Features always get a companion [Docs] issue
5. Epic label policy: Epics carry no area label (children carry labels)
6. Phase field removed — Milestones tied 1:1 to Epics replace Phase tracking
7. "Ongoing Ops" milestone closed. XOOS Phase 1 + Phase 2 merged into "XOOS".
8. decision.md template deleted. ELT pipeline template prefix changed to [Feature].
9. PR template: Fixes # → Closes #, simplified Type of Change section
10. gh_helper.py wrapper added to reduce CLI friction
11. team.md user handle mapping added for assignee resolution
Rationale: Accumulated complexity (Decision as separate type, Phase duplicating Milestones, type labels duplicating native Issue Types, templates referencing deleted labels). This overhaul simplifies hierarchy, enforces companion docs for Features, and improves Claude's ability to manage the issue lifecycle.