Skip to content

[Docs] Clarify issue taxonomy and reduce task label overuse #815

@Astro-Han

Description

@Astro-Han

Problem

The task label is overused across the open issue backlog. It currently covers UI polish, bugs, tech debt, CI false positives, tracking work, and implementation follow-ups, which makes the backlog harder to scan and filter.

Current snapshot checked on 2026-05-21:

  • 57 open issues
  • 33 labeled task
  • 10 labeled bug
  • 14 labeled enhancement
  • 13 labeled tech-debt

This is not just a backlog cleanup problem. The current templates and policy still make task the easiest bucket for maintainer/agent execution work.

Prior work to preserve

Do not repeat or undo these decisions:

  • PR ci(pr-triage): unify labeler, priority triage, and label policy #731 unified PR labeler, priority triage, and label policy into one pr-triage workflow to avoid label race failures.
  • PR docs(github): tighten PR and task templates against agent misuse #752 tightened the PR template and task issue template after agent misuse. It also documented follow-ups around issue-template restructuring and left the .github/workflows/** -> task labeler behavior as a separate decision.
  • The current label policy still treats PR type labels as exactly one of bug, enhancement, task, or documentation, and currently requires tech-debt to be paired with task. Any taxonomy change must update this policy deliberately instead of only changing prose.

Proposed taxonomy

Use one primary issue/PR type where possible:

  • bug: existing behavior is broken, incorrect, regressed, flaky, misleading, or creates false positives.
  • enhancement: new capability or user-visible workflow improvement.
  • documentation: docs, repo guidance, templates, policies, or written process.
  • tech-debt: internal cleanup, maintainability, architecture, test/quality debt, or non-user-visible refactor work.
  • task: execution-only, audit, spike, tracking, upstream-followup, or migration work without clearer bug, feature, docs, or tech-debt semantics.

task should not be the default label for "work an agent can do." It should be narrow.

Proposed changes

  • Update the task label description to narrow its meaning.
  • Decide whether tech-debt becomes a primary type label or remains supplemental but no longer requires task.
  • Update .github/scripts/label-policy-check.js and its tests to match the chosen taxonomy.
  • Update .github/pull_request_template.md type-label checklist if tech-debt becomes a primary type.
  • Update .github/ISSUE_TEMPLATE/03-task.yml with explicit "do not use this for bug / feature / docs / tech-debt" guidance.
  • Add a .github/ISSUE_TEMPLATE/04-tech-debt.yml issue form if tech-debt is promoted to a first-class issue type.
  • Add short triage guidance, either in a small .github/ISSUE_TRIAGE.md or in the issue forms, explaining when to use each type.
  • After the template/policy guardrails land, relabel existing open issues in small batches.

Non-goals

Suggested follow-up batches

After the guardrail PR lands:

  1. Relabel obvious bug/polish issues currently marked task.
  2. Relabel obvious tech-debt issues and remove unnecessary task.
  3. Review gray-area diagnostics/tracking issues one by one.

Acceptance criteria

  • New issues have a clear path for bug, feature, documentation, tech-debt, and narrow task work.
  • task is documented as a narrow execution/tracking type, not a general work bucket.
  • PR label policy, PR template checklist, and issue templates agree with each other.
  • The first PR closes or links this issue and does not perform broad backlog relabeling.

Metadata

Metadata

Assignees

No one assigned

    Labels

    P2Medium priorityciContinuous integration / GitHub ActionsdocumentationImprovements or additions to documentation

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions