From 654b066d1c8e62cdc03e895f141f2a1a678673c5 Mon Sep 17 00:00:00 2001
From: Lex Christopherson <lex@glittercowboy.com>
Date: Thu, 8 Jan 2026 08:57:21 -0600
Subject: [PATCH] feat(09-01): create UAT issues template

- Phase-scoped issues format ({phase}-{plan}-ISSUES.md)
- Separate from global ISSUES.md (enhancements)
- Severity guide and numbering conventions
- Workflow for resolution tracking
---
 get-shit-done/templates/uat-issues.md | 143 ++++++++++++++++++++++++++
 1 file changed, 143 insertions(+)
 create mode 100644 get-shit-done/templates/uat-issues.md

diff --git a/get-shit-done/templates/uat-issues.md b/get-shit-done/templates/uat-issues.md
new file mode 100644
index 000000000..ca26ae590
--- /dev/null
+++ b/get-shit-done/templates/uat-issues.md
@@ -0,0 +1,143 @@
+# UAT Issues Template
+
+Template for `.planning/phases/XX-name/{phase}-{plan}-ISSUES.md` - phase-scoped issues discovered during user acceptance testing.
+
+**Purpose:** Capture issues found during /gsd:verify-work. Unlike global ISSUES.md (for deferred enhancements), this file tracks bugs and problems in specific delivered work.
+
+**Location:** Same directory as the SUMMARY.md being tested.
+
+---
+
+## File Template
+
+```markdown
+# UAT Issues: Phase [X] Plan [Y]
+
+**Tested:** [date]
+**Source:** [path to SUMMARY.md that was tested]
+**Tester:** User via /gsd:verify-work
+
+## Open Issues
+
+### UAT-001: [Brief description]
+
+**Discovered:** [date]
+**Phase/Plan:** [XX]-[YY]
+**Severity:** [Blocker/Major/Minor/Cosmetic]
+**Feature:** [Which feature from the test checklist]
+**Description:** [User's description of the problem]
+**Expected:** [What should have happened]
+**Actual:** [What actually happened]
+**Repro:** [Steps to reproduce, if captured]
+
+### UAT-002: [Brief description]
+
+...
+
+## Resolved Issues
+
+[Moved here after /gsd:plan-fix executes and fixes are verified]
+
+### UAT-001: [Brief description]
+**Resolved:** [date] - Fixed in [phase]-[plan]-FIX.md
+**Commit:** [hash]
+
+---
+
+*Phase: XX-name*
+*Plan: YY*
+*Tested: [date]*
+```
+
+---
+
+## Severity Guide
+
+| Severity | Definition | Example |
+|----------|------------|---------|
+| **Blocker** | Feature completely unusable | App crashes on button click |
+| **Major** | Feature works but significant problem | Form submits but data not saved |
+| **Minor** | Feature usable but has issues | Button text slightly cut off |
+| **Cosmetic** | Visual only, no functional impact | Wrong shade of color |
+
+---
+
+## UAT Numbering
+
+- **Prefix:** `UAT-` (distinguishes from ISS- enhancement issues)
+- **Scope:** Per-file numbering (UAT-001, UAT-002, etc. within each file)
+- **No global numbering:** Each {phase}-{plan}-ISSUES.md has its own sequence
+
+---
+
+<good_examples>
+```markdown
+# UAT Issues: Phase 5 Plan 2
+
+**Tested:** 2025-01-15
+**Source:** .planning/phases/05-auth/05-02-SUMMARY.md
+**Tester:** User via /gsd:verify-work
+
+## Open Issues
+
+### UAT-001: Login form doesn't show validation errors
+
+**Discovered:** 2025-01-15
+**Phase/Plan:** 05-02
+**Severity:** Major
+**Feature:** User login form
+**Description:** When I enter an invalid email, nothing happens. No error message appears.
+**Expected:** Red error message below email field saying "Invalid email format"
+**Actual:** Field border turns red but no text explanation
+**Repro:**
+1. Go to /login
+2. Enter "notanemail" in email field
+3. Click Login button
+
+### UAT-002: Password field allows paste
+
+**Discovered:** 2025-01-15
+**Phase/Plan:** 05-02
+**Severity:** Cosmetic
+**Feature:** User login form
+**Description:** Can paste into password field. Minor UX inconsistency.
+**Expected:** Paste disabled (matches signup form)
+**Actual:** Paste works in login but not signup
+**Repro:** Ctrl+V in password field
+
+## Resolved Issues
+
+[None yet]
+
+---
+
+*Phase: 05-auth*
+*Plan: 02*
+*Tested: 2025-01-15*
+```
+</good_examples>
+
+<guidelines>
+**When to create:**
+- First time /gsd:verify-work finds an issue for a plan
+- One file per plan tested
+
+**Location:**
+- `.planning/phases/XX-name/{phase}-{plan}-ISSUES.md`
+- Lives alongside SUMMARY.md being tested
+
+**Difference from global ISSUES.md:**
+- Global ISSUES.md: Deferred enhancements (Rule 5 - nice-to-haves)
+- UAT ISSUES.md: Actual problems found during testing
+
+**Workflow:**
+1. /gsd:verify-work creates this file with issues
+2. /gsd:plan-fix reads this file and creates FIX.md plan
+3. After FIX.md executes, issues move to "Resolved" section
+4. File becomes historical record of what was found and fixed
+
+**Resolution:**
+- Don't delete resolved issues - move to "Resolved Issues" section
+- Include fix reference (commit hash, plan that fixed it)
+- File serves as audit trail
+</guidelines>