msd-core/get-shit-done/templates/UAT.md

UAT Template

Template for .planning/phases/XX-name/{phase}-UAT.md — persistent UAT session tracking.

---

File Template

---
status: testing | complete | diagnosed
phase: XX-name
source: [list of SUMMARY.md files tested]
started: [ISO timestamp]
updated: [ISO timestamp]
---

## Current Test
<!-- OVERWRITE each test - shows where we are -->

number: [N]
name: [test name]
expected: |
  [what user should observe]
awaiting: user response

## Tests

### 1. [Test Name]
expected: [observable behavior - what user should see]
result: [pending]

### 2. [Test Name]
expected: [observable behavior]
result: pass

### 3. [Test Name]
expected: [observable behavior]
result: issue
reported: "[verbatim user response]"
severity: major
root_cause: [filled by diagnose-issues, empty until diagnosed]
debug_session: [path to DEBUG file, empty until diagnosed]

### 4. [Test Name]
expected: [observable behavior]
result: skipped
reason: [why skipped]

...

## Summary

total: [N]
passed: [N]
issues: [N]
pending: [N]
skipped: [N]

## Issues for /gsd:plan-fix

- UAT-001: [brief summary] (blocker) - Test 3
  root_cause: [empty until diagnosed]

- UAT-002: [brief summary] (major) - Test 7
  root_cause: [empty until diagnosed]

---

<section_rules>

Frontmatter:

• status: OVERWRITE - "testing" or "complete"
• phase: IMMUTABLE - set on creation
• source: IMMUTABLE - SUMMARY files being tested
• started: IMMUTABLE - set on creation
• updated: OVERWRITE - update on every change

Current Test:

• OVERWRITE entirely on each test transition
• Shows which test is active and what's awaited
• On completion: "[testing complete]"

Tests:

• Each test: OVERWRITE result field when user responds
• result values: [pending], pass, issue, skipped
• If issue: add reported (verbatim) and severity (inferred)
• If skipped: add reason if provided
• After diagnosis: add root_cause and debug_session fields to issues

Summary:

• OVERWRITE counts after each response
• Tracks: total, passed, issues, pending, skipped

Issues for /gsd:plan-fix:

• APPEND only when issue found
• Format: - UAT-{NNN}: {summary} ({severity}) - Test {N}
• After diagnosis: add root_cause: line under each issue
• This section feeds directly into /gsd:plan-fix

</section_rules>

<diagnosis_lifecycle>

After testing complete (status: complete), if issues exist:

1. User runs diagnosis (from verify-work offer or manually)
2. diagnose-issues workflow spawns parallel debug agents
3. Each agent investigates one issue, returns root cause
4. UAT.md updated with root causes:
   • Each issue test gets root_cause: and debug_session: fields
   • Issues section gets root_cause: under each issue
5. status → "diagnosed"
6. Ready for /gsd:plan-fix with root causes

After diagnosis:

### 2. Create Top-Level Comment
expected: Submit comment via rich text editor, appears in list with author info
result: issue
reported: "works but doesn't show until I refresh the page"
severity: major
root_cause: useEffect in CommentList.tsx missing commentCount dependency
debug_session: .planning/debug/comment-not-refreshing.md

## Issues for /gsd:plan-fix

- UAT-001: Comment doesn't appear until refresh (major) - Test 2
  root_cause: useEffect in CommentList.tsx missing commentCount dependency

</diagnosis_lifecycle>

Creation: When /gsd:verify-work starts new session

• Extract tests from SUMMARY.md files
• Set status to "testing"
• Current Test points to test 1
• All tests have result: [pending]

During testing:

• Present test from Current Test section
• User responds with pass confirmation or issue description
• Update test result (pass/issue/skipped)
• Update Summary counts
• If issue: append to Issues section, infer severity
• Move Current Test to next pending test

On completion:

• status → "complete"
• Current Test → "[testing complete]"
• Commit file
• Present summary with next steps

Resume after /clear:

1. Read frontmatter → know phase and status
2. Read Current Test → know where we are
3. Find first [pending] result → continue from there
4. Summary shows progress so far

<severity_guide>

Severity is INFERRED from user's natural language, never asked.

User describes	Infer
Crash, error, exception, fails completely, unusable	blocker
Doesn't work, nothing happens, wrong behavior, missing	major
Works but..., slow, weird, minor, small issue	minor
Color, font, spacing, alignment, visual, looks off	cosmetic

Default: major (safe default, user can clarify if wrong)

</severity_guide>

<good_example>

---
status: testing
phase: 04-comments
source: 04-01-SUMMARY.md, 04-02-SUMMARY.md
started: 2025-01-15T10:30:00Z
updated: 2025-01-15T10:45:00Z
---

## Current Test

number: 4
name: Visual Nesting
expected: |
  Create 3+ level deep thread.
  Each level shows increased indentation with left border.
  Nesting caps at reasonable depth.
awaiting: user response

## Tests

### 1. View Comments on Post
expected: Comments section expands, shows count and comment list
result: pass

### 2. Create Top-Level Comment
expected: Submit comment via rich text editor, appears in list with author info
result: issue
reported: "works but doesn't show until I refresh the page"
severity: major
root_cause: useEffect in CommentList.tsx missing commentCount dependency
debug_session: .planning/debug/comment-not-refreshing.md

### 3. Reply to a Comment
expected: Click Reply, inline composer appears, submit shows nested reply
result: pass

### 4. Visual Nesting
expected: 3+ level thread shows indentation, left borders, caps at reasonable depth
result: [pending]

### 5. Delete Own Comment
expected: Click delete on own comment, removed or shows [deleted] if has replies
result: [pending]

### 6. Comment Count
expected: Post shows accurate count, increments when adding comment
result: [pending]

## Summary

total: 6
passed: 2
issues: 1
pending: 3
skipped: 0

## Issues for /gsd:plan-fix

- UAT-001: Comment doesn't appear until refresh (major) - Test 2
  root_cause: useEffect in CommentList.tsx missing commentCount dependency

</good_example>

<difference_from_issues_md>

UAT.md	ISSUES.md (global)
Created by /gsd:verify-work	Created by deviation rule 5 during execution
Tracks test session state	Tracks deferred enhancements
Phase-scoped, one per phase	Global, one per project
Feeds into /gsd:plan-fix	Feeds into /gsd:consider-issues
Contains pass/fail/skip results	Contains only deferred items

</difference_from_issues_md>