[Child of #649] Audit: Issue Template Inventory & Standardization

[ashleyshaw]

Overview

Inventory and audit of all issue templates in .github/ISSUE_TEMPLATE/ to verify standardization, completeness, and consistency.

Scope

• Inventory all .md files in .github/ISSUE_TEMPLATE/
• Check if each template has required frontmatter
• Verify each template's relationship to an issue type in issue-types.yml
• Document which templates are actively used vs. deprecated
• Check config.yml for completeness

Audit Checklist

• Create inventory spreadsheet with all templates
• Verify frontmatter structure in each template
• Cross-reference each template with issue-types.yml
• Document usage status for each template
• Check .github/ISSUE_TEMPLATE/config.yml for accuracy
• Identify deprecated or unused templates

Deliverables

• Audit report as issue comment
• Spreadsheet: Template Name | Issue Type | Frontmatter Status | Usage Status | Last Updated | Notes
• List of standardization recommendations

Related Files

• .github/ISSUE_TEMPLATE/ (all .md files)
• .github/ISSUE_TEMPLATE/config.yml
• .github/ISSUE_TEMPLATE/README.md
• .github/issue-types.yml

Related Documentation

• Issue Templates Directory
• Issue Types Guide
• Issue Creation Guide

[linear-code]

LS-828

[ashleyshaw]

Issue Template Inventory & Standardization Audit

Executive Summary

✅ All 26 issue templates have consistent frontmatter and follow the standard structure.
⚠️ 1 Critical Issue Found: Duplicate numbering (07-improvement.md + 07-user-experience-feedback.md)
⚠️ 1 Mismatch Found: "Chore" issue type exists in issue-types.yml but has no corresponding template
🟡 2 Templates Needing Mapping Review: Help/Support and User Experience Feedback have ambiguous type associations

---

Template Inventory & Frontmatter Audit

#	Template File	Issue Type	Frontmatter ✓	Last Updated	Version	Notes
01	01-task.md	Task	✅	2026-05-29	1.0.0	—
02	02-bug.md	Bug	✅	2026-05-29	1.0.0	—
03	03-feature.md	Feature	✅	2026-05-29	1.0.0	—
04	04-design.md	Design	✅	2026-05-29	1.0.0	—
05	05-epic.md	Epic	✅	2026-05-29	1.0.0	—
06	06-story.md	Story	✅	2026-05-29	1.0.0	—
07A	07-improvement.md	Improvement	✅	2026-05-29	1.0.0	Numbering conflict: Shares 07 prefix with next file
07B	07-user-experience-feedback.md	❓ Support/Design?	✅	2026-05-29	1.0.0	Critical: Duplicate 07 prefix; type mapping unclear
08	08-code-refactor.md	Code Refactor	✅	2026-05-29	1.0.0	—
09	09-build-ci.md	Build & CI	✅	2026-05-29	1.0.0	—
10	10-automation.md	Automation	✅	2026-05-29	1.0.0	—
11	11-testing-coverage.md	Test Coverage	✅	2026-05-29	1.0.0	—
12	12-performance.md	Performance	✅	2026-05-29	1.0.0	—
13	13-a11y.md	A11y	✅	2026-05-29	1.0.0	—
14	14-security.md	Security	✅	2026-05-29	1.0.0	—
15	15-compatibility.md	Compatibility	✅	2026-05-29	1.0.0	—
16	16-integration-issue.md	Integration	✅	2026-05-29	1.0.0	—
17	17-release.md	Release	✅	2026-05-29	1.0.0	—
18	18-maintenance.md	Maintenance	✅	2026-05-29	1.0.0	Also notes "Chore" in template header
19	19-documentation.md	Documentation	✅	2026-05-29	1.0.0	—
20	20-research.md	Research	✅	2026-05-29	1.0.0	—
21	21-audit.md	Audit	✅	2026-05-29	1.0.0	—
22	22-code-review.md	Code Review	✅	2026-05-29	1.0.0	—
23	23-ai-ops.md	AI Ops	✅	2026-05-29	1.0.0	—
24	24-content-modelling.md	Content Modelling	✅	2026-05-29	1.0.0	—
25	25-help.md	❓ Support/Question?	✅	2026-05-29	1.0.0	Type mapping unclear; could be Support or Question

---

Frontmatter Compliance Summary

✅ All 26 templates include the complete required frontmatter:

• file_type: "issue-template" ✅
• name (with emoji) ✅
• description ✅
• version: "1.0.0" ✅
• last_updated: "2026-05-29" ✅
• category: "github-templates" ✅

No missing or malformed frontmatter found.

---

Template ↔ Issue Type Mapping Analysis

Templates with Direct 1:1 Mappings (24 templates) ✅

Template	Issue Type	Match
01-task.md	Task	✅ Perfect
02-bug.md	Bug	✅ Perfect
03-feature.md	Feature	✅ Perfect
04-design.md	Design	✅ Perfect
05-epic.md	Epic	✅ Perfect
06-story.md	Story	✅ Perfect
07-improvement.md	Improvement	✅ Perfect
08-code-refactor.md	Code Refactor	✅ Perfect
09-build-ci.md	Build & CI	✅ Perfect
10-automation.md	Automation	✅ Perfect
11-testing-coverage.md	Test Coverage	✅ Perfect
12-performance.md	Performance	✅ Perfect
13-a11y.md	A11y	✅ Perfect
14-security.md	Security	✅ Perfect
15-compatibility.md	Compatibility	✅ Perfect
16-integration-issue.md	Integration	✅ Perfect
17-release.md	Release	✅ Perfect
18-maintenance.md	Maintenance	✅ Perfect
19-documentation.md	Documentation	✅ Perfect
20-research.md	Research	✅ Perfect
21-audit.md	Audit	✅ Perfect
22-code-review.md	Code Review	✅ Perfect
23-ai-ops.md	AI Ops	✅ Perfect
24-content-modelling.md	Content Modelling	✅ Perfect

Templates with Ambiguous Mappings (2 templates) ⚠️

1. 25-help.md ("❓ Help / Support")

   • Could map to: Support (exact match in issue-types.yml)
   • Could map to: Question (also in issue-types.yml)
   • Recommendation: Map to Support as primary

2. 07-user-experience-feedback.md ("💡 User Experience Feedback")

   • Could map to: Support (if feedback is support-related)
   • Could map to: Design (if feedback is design-focused)
   • Could map to: Improvement (if feedback drives product improvements)
   • Recommendation: Clarify scope—consider if this should be merged with 04-design.md or made distinct from 25-help.md

Issue Types Without Templates (1 type) ⚠️

• Chore (defined in issue-types.yml but no template file exists)
  • Currently handled by: 18-maintenance.md template (header notes "Maintenance / Chore Summary")
  • Recommendation: Either create a dedicated chore.md template or document that Chore issues use the Maintenance template

---

Critical Issues & Recommendations

1. 🔴 CRITICAL: Duplicate File Numbering

Files: 07-improvement.md and 07-user-experience-feedback.md

Impact: Confusing; breaks sequential ordering; violates naming convention

Recommended Fix:

• Rename 07-user-experience-feedback.md → 08-user-experience-feedback.md
• Cascade renumber all subsequent files (+1):
  • 08-code-refactor.md → 09-code-refactor.md
  • 09-build-ci.md → 10-build-ci.md
  • (and so on through 25-help.md)

---

2. 🟡 ISSUE: Chore Issue Type Missing Template

Status: Chore is defined in issue-types.yml but no dedicated template file exists

Current Workaround: 18-maintenance.md template header notes "Maintenance / Chore Summary"

Recommended Fix (choose one):

• Option A (Recommended): Create XX-chore.md template as a distinct type
• Option B: Update 18-maintenance.md frontmatter to map to both "Maintenance" and "Chore"
• Option C: Remove "Chore" from issue-types.yml if it's not actively used

---

3. 🟡 ISSUE: User Experience Feedback Template Type Mapping Unclear

File: 07-user-experience-feedback.md

Problem: No explicit mapping to an issue type; unclear if this is Support, Design, or Improvement

Recommended Actions:

• Clarify the intended audience and purpose (product feedback vs. design critique vs. support request)
• Update frontmatter to include an issue_type field
• Decide: Is this a distinct type, or should it be merged with another template?

---

4. 🟡 ISSUE: Help/Support Template Type Mapping Needs Clarification

File: 25-help.md

Current State: Maps to either Support or Question issue type (ambiguous)

Recommended Action:

• Update frontmatter to explicitly define intended issue type
• Verify GitHub config.yml reflects this mapping
• Update documentation to clarify when to use Support vs. Question

---

Config.yml Review

Current state:

blank_issues_enabled: false
contact_links:
  - name: LightSpeed WP Support
    url: https://lightspeedwp.agency
    about: For paid support inquiries, please contact us directly via our website.

Status: ✅ Correctly disables blank issues and routes support inquiries
Recommendation: Add comments linking to canonical template documentation

---

Standardization Checklist

• All 26 templates have complete, consistent frontmatter
• All templates follow naming convention (NN-name.md)
• All templates include emoji and clear description
• All templates have version "1.0.0"
• All templates have recent last_updated date (2026-05-29)
• ⚠️ Duplicate numbering issue (07-improvement.md + 07-user-experience-feedback.md)
• ⚠️ Chore type has no dedicated template (workaround: uses Maintenance template)
• ⚠️ User Experience Feedback type mapping is undefined
• ⚠️ Help/Support type mapping needs clarification

---

Deliverables

Summary

• Total Templates Inventoried: 26 files
• Templates with Complete Frontmatter: 26/26 ✅
• Templates with Direct Type Mapping: 24/26 ✅
• Templates Needing Clarification: 2/26 ⚠️
• Critical Issues: 1 (duplicate numbering)
• Medium Issues: 2 (type mapping ambiguity)
• Low Issues: 1 (Chore template missing)

Recommendations Summary

Issue	Severity	Action	Effort
Duplicate 07 numbering	Critical	Rename + cascade renumber 18 files	M
Chore type lacks template	Medium	Create dedicated template or update config	S-M
User Experience Feedback type unclear	Medium	Add issue_type field, clarify purpose	S
Help/Support type unclear	Medium	Add issue_type field to clarify mapping	S

---

Next Steps

1. PR [Child of #649] Audit: Issue Template → Automation Trigger Mapping #655 (Issue Template → Automation Trigger Mapping) should reference these findings
2. PR [Child of #649] Audit: Issue Labeling Rules in labeler.yml #656 (Issue Labeling Rules in labeler.yml) should verify type mappings from this audit
3. PR [Child of #649] Implement: Clear AI Agent Instructions for Issue Creation #657 (Clear AI Agent Instructions) should document standardized template usage

---

Audit Completed: 2026-05-31
Template Count: 26 files + config.yml
Frontmatter Compliance: 100% (26/26)
Type Mapping Completeness: 92% (24/26 with clear mapping)

---

Generated by Claude Code