Skip to content

Universal GitHub Issue Template

  • Date: 2026-03-17
  • Status: Accepted
  • Tags: tooling workflow github

Context

30 GitHub repositories spanning Terraform modules, Python AI agents, Claude skills, and personal projects had no consistent issue filing structure. Issues were filed ad-hoc, making triage, prioritisation, and AI agent execution (via Cyrus) inconsistent and noisy.

Cyrus — the primary AI agent used to execute GitHub issues — benefits from predictable issue structure: a clear objective, concrete acceptance criteria for self-verification loops, and agent-specific hints (process notes, file references to reduce codebase exploration).

Decision

Adopt a single universal Markdown issue template (.github/ISSUE_TEMPLATE/issue.md) deployed across all active repositories. A single template self-sorts via Issue Type checkboxes rather than requiring separate per-type templates, reducing maintenance overhead.

Key fields and rationale:

Field Purpose
Issue Type checkboxes Self-classifying; single template covers Bug / Feature / Task / Question / Docs
Context Prevents Cyrus from implementing in the wrong direction
Objective One concrete task statement per issue
Acceptance Criteria Cyrus's self-verification loop (iterates up to 3× against these)
Steps to Reproduce Optional; delete for non-bugs
Environment Covers union of Terraform + Python + CLI repo types
Process Notes Agent-specific: methodology hints, constraints, things to avoid
References File paths and docs links to reduce Cyrus's exploration overhead

A config.yml with blank_issues_enabled: false enforces template use across all repos.

Auto-label needs-triage applied on all new issues via frontmatter — enables triage automation where configured.

Alternatives Considered

Option Why Rejected
YAML issue forms More structured but too rigid for a solo developer; poor UX for quick captures; requires separate files per issue type
Per-repo templates Maximum flexibility but high maintenance; inconsistent Cyrus experience across repos
GitHub org-level community health files (single .github repo) Considered for future; currently using per-repo deployment for explicit control and visibility

Consequences

Positive:

  • Cyrus receives consistent, structured context → fewer clarification round-trips per issue
  • needs-triage label enables automated triage workflows across repos
  • Single template → one place to evolve if structure changes
  • Human contributors get clear guidance without multiple template choices

Negative / Trade-offs:

  • One template covers multiple issue types → contributors delete unused sections manually
  • Cannot enforce field completion (Markdown templates, not YAML forms)
  • Repos with existing custom templates (e.g., claude-code-skill-factory release checklist) must manage coexistence

Ongoing obligations:

  • Update template across repos if structure changes materially (consider scripting via gh api)
  • Evaluate YAML forms if collaborators join and enforcement becomes valuable

ADRs are immutable. If this decision changes, create a new ADR with status "Superseded by" pointing here, and update this record's status.