ARFC-1009: Issue-Type Taxonomy for the Use-Case Backlog Hierarchy

Status

Implemented Date: 2026-07-24 Last Call Date: 2026-08-05 Publication Date: 2026-08-05 Version: 0.6

Scope note: This ARFC documents a 100% internal engineering-process design — it governs how issues in codermerlin.academy-use-cases and its downstream implementation repositories (codermerlin.academy-backend, -frontend, -ui-ux) are typed and parented. It has no effect on the ĀYŌDÈ platform, the Codermerlin Academy API, or any developer/end-user -visible behavior. It is filed here, rather than as a plain docs/silicon-based-how/ note or a GitHub issue body (the normally-prescribed vehicles for internal tooling per this repository’s ARFC scope gate), per explicit operator direction on 2026-07-23 — following the same precedent as ARFC-1008 — so that this design carries the same Draft → Last Call → Published review lifecycle as a platform-facing proposal.

Abstract

This RFC formalizes a five-tier issue hierarchy for the ĀYŌDÈ use-case backlog — Theme, Epic, Requirement, per-discipline breakdown, and Task — and assigns each tier exactly one GitHub Issue Type, so that an issue’s type alone identifies its level without needing to walk its parent chain or inspect which repository it lives in. Two new organization-level Issue Types, Theme and Epic, are introduced; four existing types (Use-Case, Feature, Design, Task) are reassigned to specific tiers where their current usage is ambiguous or split across levels. Bug and Incident are explicitly excluded from the level scheme as reactive, unplanned work that can attach at any tier. The hierarchy itself is carried entirely by GitHub’s native, cross-repository Sub-issues relationships — no labels, checklists, or external tracker are introduced.

Table of Contents

  1. Introduction
  2. Motivation
  3. Specification
  4. Security Considerations
  5. Backward Compatibility
  6. References
  7. Author

1. Introduction

codermerlin.academy-use-cases holds the product’s use-case backlog (156 issues as of 2026-07-23). Inspecting the backlog via GitHub’s GraphQL parent/subIssues connections shows a real, already-in-use hierarchy: a top issue per product area (identified today only by a title prefix such as “Instructor Studio:” or “Course Helm:”), root issues beneath it representing cohesive capabilities, child issues beneath those breaking a capability into individual requirements, and — for requirements that have been analyzed — further child issues in codermerlin.academy-backend, -frontend, and -ui-ux carrying the actual per-discipline implementation work. This hierarchy exists structurally today (via Sub-issues), but nothing about an issue’s type currently identifies which tier it occupies: the same type is used across multiple tiers, several tiers are predominantly untyped, and no type exists at all for the top two levels.

2. Motivation

2.1 Current State

2.2 Use Cases

2.3 Design Goals

  1. Every level maps to exactly one Issue Type — a type answers “what level is this,” not merely “what kind of ticket is this” — with Bug and Incident as the sole, deliberate exceptions (§3.3).
  2. Minimize new type creation: reuse an existing organization Issue Type wherever its description already fits a tier; only introduce a new type where none of the six existing types fit. This is why only Theme and Epic are new — the other four tiers reuse Use-Case, Feature, Design, and Task.
  3. Keep GitHub’s native Sub-issues relationship as the sole hierarchy mechanism — no labels, checklists, or external tracker — consistent with how use-case-backend-analyze already links use-cases to backend tracking issues.
  4. No change to platform-facing behavior: this taxonomy governs backlog bookkeeping only.
  5. Constrain all work under this proposal — type migration, hierarchy formalization, and label alignment alike — to exactly four repositories: codermerlin.academy-use-cases, codermerlin.academy-ui-ux, codermerlin.academy-frontend, and codermerlin.academy-backend. No other organization repository is in scope.

3. Specification

3.1 Level / Type / Repository Table

Level Tier Repository Issue Type
0 Theme codermerlin.academy-use-cases Theme
1 Epic codermerlin.academy-use-cases Epic
2 Requirement (incl. former Design Brief: issues) codermerlin.academy-use-cases Use-Case
3 Discipline breakdown — backend/frontend codermerlin.academy-backend, codermerlin.academy-frontend Feature
3 Discipline breakdown — UI/UX codermerlin.academy-ui-ux Design
4 Implementation task codermerlin.academy-backend, -frontend, -ui-ux Task
— Defect (not level-bound) wherever filed Bug
— Production incident (not level-bound) wherever filed Incident

Level 4 is a reserved tier: no issue sampled during this design currently has a fifth-level child. It exists in the scheme for when a Feature or Design breakdown item needs to be split into multiple discrete implementation tasks, not because such splits exist today.

3.2 Hierarchy Diagram

graph TD
    Theme["Theme<br/>Type: Theme<br/>use-cases repo"]
    Epic["Epic<br/>Type: Epic<br/>use-cases repo"]
    Requirement["Requirement<br/>Type: Use-Case<br/>use-cases repo"]
    FeatureBE["Backend breakdown<br/>Type: Feature<br/>backend repo"]
    FeatureFE["Frontend breakdown<br/>Type: Feature<br/>frontend repo"]
    DesignUX["UI/UX breakdown<br/>Type: Design<br/>ui-ux repo"]
    TaskBE["Implementation task<br/>Type: Task<br/>backend repo"]
    TaskFE["Implementation task<br/>Type: Task<br/>frontend repo"]
    TaskUX["Implementation task<br/>Type: Task<br/>ui-ux repo"]
    Bug["Bug<br/>Type: Bug<br/>any repo, any level"]
    Incident["Incident<br/>Type: Incident<br/>any repo, any level"]

    Theme --> Epic
    Epic --> Requirement
    Requirement --> FeatureBE
    Requirement --> FeatureFE
    Requirement --> DesignUX
    FeatureBE --> TaskBE
    FeatureFE --> TaskFE
    DesignUX --> TaskUX
    Bug -.->|reactive, not part of planned decomposition| Requirement
    Incident -.->|reactive, not part of planned decomposition| Epic

Solid arrows are the planned, top-down decomposition (one Issue Type per level, per §3.1). Dashed arrows show Bug/Incident as attachable at any tier — the diagram shows one representative attachment point for each, not an exhaustive set; either type may occur at any level in practice.

3.3 Bug and Incident as Level-Agnostic Exceptions

Bug and Incident are intentionally excluded from the one-type-per-level rule in §2.3. Both represent reactive work discovered against something that already exists, not a piece of a top-down plan — a defect can be found in an Epic’s overall behavior, in a single Requirement, or in a shipped implementation Task, and forcing it into the level of whatever it was found against would misrepresent unplanned work as planned deliverables. These two types therefore carry no level semantics and may parent to, or be parented by, an issue at any tier.

3.4 Migration Inventory

Based on the current-state counts in §2.1, adopting this taxonomy requires retyping existing issues — it is not solely additive:

Tier Issue count Current types Target type
Epic 22 Use-Case (18), Feature (2), untyped (2) Epic
Requirement 112 Task (51), untyped (48, incl. 10 Design Brief:), Feature (13) Use-Case
Discipline breakdown (BE/FE) 59 fanned-out requirements’ worth, count TBD by repo predominantly untyped, one observed Task Feature
Discipline breakdown (UI/UX) subset of the above untyped Design
Implementation task (Level 4) 0 observed — Task (reserved, no backfill needed)

The 22 already-retired orphan issues (§2.1) are out of scope for this migration — they carry no type going forward and are not expected to re-enter the hierarchy.

3.5 Worked Example

Epic #19 (“Instructor Studio: Resource Upload & Library Management”, codermerlin.academy-use-cases) parents Requirement #31 (“Sub-Issue: Select Library / Realm for Source Upload”, same repository), which in turn parents implementation issues in separate repositories: #1698 (“Frontend requirements for use-case #31…”, codermerlin.academy-frontend) and #1560 (“Analyze backend requirements for use-case #31…”, codermerlin.academy-backend). Under this taxonomy: #19 → Epic, #31 → Use-Case, #1698/#1560 → Feature (with a further Task child if either is later split into discrete implementation steps).

3.6 Complete Issue Type Reference

All eight organization Issue Types, with their live description field (the two new types’ descriptions were set by the operator directly in GitHub on 2026-07-23, matching this proposal):

Issue Type Description Level (§3.1)
Theme A product area grouping related epics 0
Epic A cohesive capability grouping related use-cases 1
Use-Case A documented user workflow, requirement, or scenario 2
Feature A request, idea, or new functionality 3 (backend/frontend)
Design A documented UI/UX artifact 3 (ui-ux)
Task A discrete unit of work associated with a bug or feature 4
Bug A defect causing incorrect behavior not level-bound
Incident A production event causing user or operational impact not level-bound

3.7 Fourth Theme: FlightPath and Legacy Label Resolution

On 2026-07-23, after the initial three-theme migration (§3.4), the fset-* label alignment work was extended to resolve five pre-existing fset-* labels that had no corresponding Theme (flagged as an open question in an earlier revision of §5):

Of the 67 fset-FlightPath issues, 54 were already closed (historical record) and were left as direct, unparented theme-FlightPath label holders — not forced into the Epic/Use-Case chain, since retroactively modeling a mostly-dead legacy initiative into cohesive requirements was judged to add fabricated structure without planning value. The 13 open issues were split:

This produced the first real Level 4 (Task) instances anywhere in the hierarchy, discovered rather than fabricated: #1560 (“Flight Path Instructor Studio Upload”) already natively parented #1563 and #1564 via GitHub Sub-issues before this design existed, and #884 (“Flight path: entry hub (dashboard)”) already parented backend #860 the same way. All three were retyped to Task in place — the existing parent links were preserved rather than flattened, since they were already structurally correct. This confirms Level 4 is a real, populated tier, not merely reserved (contrast with §3.4’s “0 observed” at initial migration time).

3.8 Automation Invariants

Four invariants have been proposed (as of 2026-07-24) for the org-level GitHub issue-lifecycle automation App (ARFC-1008), to keep this taxonomy self-maintaining rather than relying on manual hygiene. Invariants 1–3 concern the Theme/Epic/Use-Case/Feature/Design/Task hierarchy this ARFC defines; Invariant 4 does not — it is documented here purely because ARFC-1008 is marked Implemented (a closed record of what is actually deployed) and this ARFC is this App’s established location for new, not-yet-implemented proposals, not because Milestone synchronization has any topical relationship to the issue-type taxonomy above.

# Invariant Issue Auto-correct?
1 Any issue that is Theme-typed, or has an ancestor (via the Sub-issues chain, walked to the root) typed Theme, must carry exactly one theme-* label matching the one currently on its root Theme issue. Bug/Incident issues with no such ancestor are exempt from the derived-value check but still bounded to at most one theme-* label. #2822 Yes
2 Any issue reachable from a root Theme via the Sub-issues chain must carry the Issue Type required by its depth (§3.1’s table: 0=Theme, 1=Epic, 2=Use-Case, 3=Feature/Design depending on repo, 4+=Task, uncapped). Bug/Incident are fully exempt regardless of depth. #2823 Yes (initial implementation — see #2823 for a deferred flag-only mode considered and postponed)
3 On Use-Case creation (issues.opened), generate the Use-Case’s full level-3 discipline breakdown per §3.1: one Analyze: <title> child in EACH of the three implementation repos — Feature in codermerlin.academy-backend, Feature in codermerlin.academy-frontend, Design in codermerlin.academy-ui-ux — each linked as a (cross-repo) sub-issue of the Use-Case, so every Use-Case acquires all three discipline stubs without manual hygiene. On a subsequent Use-Case title change (issues.edited), propagate the new title to EACH discipline child whose title begins with Analyze: <old-title> — matched against the payload’s changes.title.from, never a fuzzy guess. Per-discipline idempotent (a webhook redelivery mints no duplicate; only missing discipline children are created; propagation is a no-op when a child is absent or already renamed) and loop-safe (the generated children are Feature/Design, not Use-Case, so their own issues.opened cannot re-trigger generation). #2830 Yes (generative + title-propagating)
4 On a milestone webhook event (created/closed/opened/edited/deleted) sourced from codermerlin.academy-use-cases only (events from the three follower repos are never a trigger — this is what keeps propagation one-directional and loop-safe), re-read the source milestone’s current title/description/due_on/state and push it to codermerlin.academy-backend/-frontend/-ui-ux, matched by title (milestones carry no cross-repo ID). Missing → create; present-but-diverged → update; title renamed (changes.title.from) → rename the follower’s matching milestone first, never a fuzzy guess. deleted removes the matching-titled milestone in each follower. Per-repository idempotent (re-reading live state makes a redelivery a no-op wherever already synced). #2920 Yes (propagating; deliberately one-directional — a direct edit made straight to a follower’s own milestone is never observed or reverted, since the App does not subscribe to milestone events on the follower repos at all)

Invariants 1 and 2 are designed to be fully self-updating: neither requires a code change, redeploy, or configuration update when a theme is added or retired. Invariant 1’s expected value is read live off the root Theme issue’s own label at enforcement time (never a hardcoded theme list); invariant 2’s expected value depends only on structural depth and repository — a static mapping fixed by this ARFC, not by which theme a branch belongs to — so it requires no per-theme awareness at all. Both reuse the same “walk the Sub-issues ancestor chain” primitive ARFC-1008 §3.7 already established for parent/sub-issue status roll-up.

Invariant 3 differs in kind: it is generative and title-propagating rather than corrective. It mints the three per-discipline Analyze: stubs (the §3.1 level-3 breakdown — backend Feature, frontend Feature, UI/UX Design) on Use-Case creation and keeps each derived child’s title in sync with its parent, reacting to issues.opened / issues.edited (and reusing ARFC-1008 §3.7’s sub-issue linkage, here cross-repo) rather than the ancestor-walk. It only creates the stubs and maintains their titles; the actual analysis of each discipline’s child into implementation tasks remains the discipline workflow’s responsibility (for backend, use-case-backend-analyze), so this invariant adds automation without pre-empting that human/agent judgment.

Invariant 4 is unrelated to the Theme/Epic/Use-Case hierarchy: it keeps release Milestones synchronized from codermerlin.academy-use-cases (established 2026-07-24 as the canonical source, after a one-time manual sync brought codermerlin.academy-backend/-frontend/-ui-ux into full parity — 27 milestones each, matching title/description/due_on/state) out to the three implementation repos, matched by title rather than any cross-repo ID (Milestones have none). Like Invariant 3, it reuses the “match a rename against changes.title.from, never a fuzzy guess” discipline. Its one-directional design is deliberate, not an oversight: the App never subscribes to milestone events on the follower repos, so a direct edit made straight to a follower’s own milestone is simply invisible to it — divergence protection (as opposed to source→follower propagation) would be a separate invariant, out of scope here. Empirical implementation note: the Milestones API silently stores the wrong calendar day (one earlier) when given a midnight-UTC due_on (T00:00:00Z) — confirmed via raw REST input, not a gh CLI artifact. Any due_on this invariant writes must be normalized to a non-midnight time (e.g. noon UTC) to avoid every propagated date landing one day early.

4. Security Considerations

This proposal changes only Issue Type metadata and Sub-issues linkage on existing GitHub issues. It grants no new permissions, alters no API/schema/privilege surface, and has no runtime component. The only operational risk is a bulk mistyping during migration (§3.4); this is mitigated by verifying the migration script’s output on a small batch per repository before applying it across the full inventory.

5. Backward Compatibility

This proposal has no effect on the ĀYŌDÈ platform or Codermerlin Academy API surface (see the Scope note in Status).

Within its own scope:

6. References

7. Author

ĀYŌDÈ Development Team Codermerlin Academy Architecture