Universal GitHub Issue Template¶
- Date: 2026-03-17
- Status: Accepted
- Tags:
toolingworkflowgithub
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-triagelabel 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-factoryrelease 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.