From 9e0808b4095aaf1027f41c4dad3191e4aad983c3 Mon Sep 17 00:00:00 2001 From: Lex Christopherson Date: Wed, 14 Jan 2026 09:56:09 -0600 Subject: [PATCH] feat: redesign verify-work as conversational UAT with persistent state - One test at a time instead of full checklist upfront - Plain text responses instead of AskUserQuestion forms - Severity inferred from description, never asked - Persistent UAT.md survives /clear (like debug workflow) - Single file per phase replaces per-plan ISSUES.md - Updated plan-fix to read from UAT.md Co-Authored-By: Claude --- commands/gsd/plan-fix.md | 148 ++++---- commands/gsd/verify-work.md | 68 ++-- get-shit-done/templates/UAT.md | 214 ++++++++++++ get-shit-done/templates/uat-issues.md | 143 -------- get-shit-done/workflows/verify-work.md | 456 ++++++++++++++++--------- 5 files changed, 635 insertions(+), 394 deletions(-) create mode 100644 get-shit-done/templates/UAT.md delete mode 100644 get-shit-done/templates/uat-issues.md diff --git a/commands/gsd/plan-fix.md b/commands/gsd/plan-fix.md index d0270ddb9..80ce8cc1e 100644 --- a/commands/gsd/plan-fix.md +++ b/commands/gsd/plan-fix.md @@ -1,7 +1,7 @@ --- name: gsd:plan-fix description: Plan fixes for UAT issues from verify-work -argument-hint: "[plan, e.g., '04-02']" +argument-hint: "" allowed-tools: - Read - Bash @@ -14,8 +14,8 @@ allowed-tools: Create FIX.md plan from UAT issues found during verify-work. -Purpose: Plan fixes for issues logged in phase-scoped ISSUES.md files. -Output: {plan}-FIX.md in the phase directory, ready for execution. +Purpose: Plan fixes for issues logged in {phase}-UAT.md. +Output: {phase}-FIX.md in the phase directory, ready for execution. @@ -24,9 +24,8 @@ Output: {plan}-FIX.md in the phase directory, ready for execution. -Plan number: $ARGUMENTS (required - e.g., "04-02" or "09-01") +Phase: $ARGUMENTS (required - e.g., "4") -**Load project state:** @.planning/STATE.md @.planning/ROADMAP.md @@ -34,52 +33,68 @@ Plan number: $ARGUMENTS (required - e.g., "04-02" or "09-01") -**Parse plan argument:** +**Parse phase argument:** -$ARGUMENTS should be a plan number like "04-02" or "09-01". -Extract phase number (XX) and plan number (NN). +$ARGUMENTS should be a phase number like "4" or "04". If no argument provided: ``` -Error: Plan number required. +Error: Phase number required. -Usage: /gsd:plan-fix 04-02 +Usage: /gsd:plan-fix 4 -This creates a fix plan from .planning/phases/XX-name/04-02-ISSUES.md +This creates a fix plan from .planning/phases/04-name/04-UAT.md ``` Exit. -**Find ISSUES.md file:** +**Find UAT.md file:** -Search for matching ISSUES.md: ```bash -ls .planning/phases/*/{plan}-ISSUES.md 2>/dev/null +ls .planning/phases/${PHASE_ARG}*/*-UAT.md 2>/dev/null ``` If not found: ``` -No ISSUES.md found for plan {plan}. +No UAT.md found for phase {phase}. -ISSUES.md files are created by /gsd:verify-work when UAT finds issues. -If no issues were found during testing, no fix plan is needed. +UAT.md files are created by /gsd:verify-work during testing. +Run /gsd:verify-work {phase} first. +``` +Exit. + +If found but status is "testing": +``` +UAT session still in progress. + +Run /gsd:verify-work to complete testing first. ``` Exit. -**Read issues:** +**Read issues from UAT.md:** + +Read the "Issues for /gsd:plan-fix" section. + +If section is empty or says "[none yet]": +``` +No issues found in UAT.md. + +All tests passed - no fix plan needed. +``` +Exit. -Read the ISSUES.md file. Parse each issue: - ID (UAT-XXX) -- Title -- Severity (critical/major/minor) -- Description/steps to reproduce -- Acceptance criteria +- Brief summary +- Severity (blocker/major/minor/cosmetic) +- Test number (for context) -Count total issues by severity. +Also read the corresponding test from "Tests" section to get: +- expected behavior +- reported issue (verbatim user description) @@ -87,42 +102,50 @@ Count total issues by severity. For each issue (or logical group): - Create one task per issue OR -- Group related minor issues into single task +- Group related cosmetic/minor issues into single task Task structure: ```xml - Fix UAT-001: [issue title] - [affected files from issue] + Fix UAT-{NNN}: {issue summary} + [affected files - infer from test context] -[What to fix based on issue description] -[Reference original acceptance criteria] +**Issue:** {verbatim reported description} +**Expected:** {from test} + +[Specific fix approach] - [Test that issue is resolved] - [Issue acceptance criteria met] + +- Reproduce original issue - confirm fixed +- {expected behavior} now works correctly + + UAT-{NNN} resolved - {expected behavior} works ``` -Prioritize: critical → major → minor +Prioritize: blocker → major → minor → cosmetic **Write FIX.md:** -Create `.planning/phases/XX-name/{plan}-FIX.md`: +Create `.planning/phases/XX-name/{phase}-FIX.md`: ```markdown --- phase: XX-name -plan: {plan}-FIX +plan: {phase}-FIX type: fix +wave: 1 +depends_on: [] +autonomous: true --- -Fix {N} UAT issues from plan {plan}. +Fix {N} UAT issues from phase {phase}. -Source: {plan}-ISSUES.md -Priority: {critical count} critical, {major count} major, {minor count} minor +Source: {phase}-UAT.md +Priority: {blocker count} blocker, {major count} major, {minor count} minor, {cosmetic count} cosmetic @@ -135,10 +158,11 @@ Priority: {critical count} critical, {major count} major, {minor count} minor @.planning/ROADMAP.md **Issues being fixed:** -@.planning/phases/XX-name/{plan}-ISSUES.md +@.planning/phases/XX-name/{phase}-UAT.md -**Original plan for reference:** -@.planning/phases/XX-name/{plan}-PLAN.md +**Original plans for reference:** +@.planning/phases/XX-name/{phase}-01-PLAN.md +[other relevant plans] @@ -147,20 +171,20 @@ Priority: {critical count} critical, {major count} major, {minor count} minor Before declaring plan complete: -- [ ] All critical issues fixed +- [ ] All blocker issues fixed - [ ] All major issues fixed -- [ ] Minor issues fixed or documented as deferred -- [ ] Original acceptance criteria from issues met +- [ ] Minor/cosmetic issues fixed or documented as deferred +- [ ] Each fix verified against original reported issue -- All UAT issues from {plan}-ISSUES.md addressed +- All UAT issues from {phase}-UAT.md addressed - Tests pass -- Ready for re-verification +- Ready for re-verification with /gsd:verify-work {phase} -After completion, create `.planning/phases/XX-name/{plan}-FIX-SUMMARY.md` +After completion, create `.planning/phases/XX-name/{phase}-FIX-SUMMARY.md` ``` @@ -169,37 +193,39 @@ After completion, create `.planning/phases/XX-name/{plan}-FIX-SUMMARY.md` **Offer execution:** ``` ---- +## Fix Plan Created -## ✓ Fix Plan Created - -**{plan}-FIX.md** — {N} issues to fix +**{phase}-FIX.md** — {N} issues to fix | Severity | Count | |----------|-------| -| Critical | {n} | +| Blocker | {n} | | Major | {n} | | Minor | {n} | +| Cosmetic | {n} | --- -Would you like to: -1. Execute the fix plan now -2. Review the plan first -3. Modify the plan before executing - ---- +Next steps: +- Execute: `/gsd:execute-plan .planning/phases/XX-name/{phase}-FIX.md` +- Review plan first: `cat .planning/phases/XX-name/{phase}-FIX.md` +- Re-test after fixes: `/gsd:verify-work {phase}` ``` -Use AskUserQuestion to get response. -If execute: `/gsd:execute-plan .planning/phases/XX-name/{plan}-FIX.md` +Use AskUserQuestion: +- header: "Next" +- question: "What would you like to do?" +- options: + - "Execute fix plan" — Run the fixes now + - "Review plan first" — Look at the plan before executing + - "Done for now" — Come back later -- [ ] ISSUES.md found and parsed +- [ ] UAT.md found and issues parsed - [ ] Fix tasks created for each issue - [ ] FIX.md written with proper structure -- [ ] User offered to execute or review +- [ ] User offered next steps diff --git a/commands/gsd/verify-work.md b/commands/gsd/verify-work.md index 7ef7f322c..e8e85776f 100644 --- a/commands/gsd/verify-work.md +++ b/commands/gsd/verify-work.md @@ -1,7 +1,7 @@ --- name: gsd:verify-work -description: Guide manual user acceptance testing of recently built features -argument-hint: "[optional: phase or plan number, e.g., '4' or '04-02']" +description: Validate built features through conversational UAT +argument-hint: "[phase number, e.g., '4']" allowed-tools: - Read - Bash @@ -9,63 +9,57 @@ allowed-tools: - Grep - Edit - Write - - AskUserQuestion --- -Guide the user through manual acceptance testing of recently built features. +Validate built features through conversational testing with persistent state. -Purpose: Validate that what Claude thinks was built actually works from the user's perspective. The USER performs all testing — Claude generates the test checklist, guides the process, and captures issues. +Purpose: Confirm what Claude built actually works from user's perspective. One test at a time, plain text responses, no interrogation. -Output: Validation of features, any issues logged to phase-scoped ISSUES.md +Output: {phase}-UAT.md tracking all test results, issues logged for /gsd:plan-fix @~/.claude/get-shit-done/workflows/verify-work.md -@~/.claude/get-shit-done/templates/uat-issues.md +@~/.claude/get-shit-done/templates/UAT.md -Scope: $ARGUMENTS (optional) -- If provided: Test specific phase or plan (e.g., "4" or "04-02") -- If not provided: Test most recently completed plan +Phase: $ARGUMENTS (optional) +- If provided: Test specific phase (e.g., "4") +- If not provided: Check for active sessions or prompt for phase -**Load project state:** @.planning/STATE.md - -**Load roadmap:** @.planning/ROADMAP.md -1. Validate arguments (if provided, parse as phase or plan number) -2. Find relevant SUMMARY.md (specified or most recent) -3. Follow verify-work.md workflow: - - Extract testable deliverables - - Generate test checklist - - Guide through each test via AskUserQuestion - - Collect and categorize issues - - Log issues to `.planning/phases/XX-name/{phase}-{plan}-ISSUES.md` - - Present summary with verdict -4. Offer next steps based on results: - - If all passed: Continue to next phase - - If issues found: `/gsd:plan-fix {phase} {plan}` to create fix plan +1. Check for active UAT sessions (resume or start new) +2. Find SUMMARY.md files for the phase +3. Extract testable deliverables (user-observable outcomes) +4. Create {phase}-UAT.md with test list +5. Present tests one at a time: + - Show expected behavior + - Wait for plain text response + - "yes/y/next" = pass, anything else = issue (severity inferred) +6. Update UAT.md after each response +7. On completion: commit, present summary, offer next steps -- Don't run automated tests (that's for CI/test suites) -- Don't make assumptions about test results — USER reports outcomes -- Don't skip the guidance — walk through each test -- Don't dismiss minor issues — log everything user reports -- Don't fix issues during testing — capture for later +- Don't use AskUserQuestion for test responses — plain text conversation +- Don't ask severity — infer from description +- Don't present full checklist upfront — one test at a time +- Don't run automated tests — this is manual user validation +- Don't fix issues during testing — log for /gsd:plan-fix -- [ ] Test scope identified from SUMMARY.md -- [ ] Checklist generated based on deliverables -- [ ] User guided through each test -- [ ] All test results captured (pass/fail/partial/skip) -- [ ] Any issues logged to phase-scoped ISSUES.md (not global) -- [ ] Summary presented with verdict -- [ ] User knows next steps based on results +- [ ] UAT.md created with tests from SUMMARY.md +- [ ] Tests presented one at a time with expected behavior +- [ ] Plain text responses (no structured forms) +- [ ] Severity inferred, never asked +- [ ] File updated after each response (survives /clear) +- [ ] Committed on completion +- [ ] Clear next steps based on results diff --git a/get-shit-done/templates/UAT.md b/get-shit-done/templates/UAT.md new file mode 100644 index 000000000..996bcb61a --- /dev/null +++ b/get-shit-done/templates/UAT.md @@ -0,0 +1,214 @@ +# UAT Template + +Template for `.planning/phases/XX-name/{phase}-UAT.md` — persistent UAT session tracking. + +--- + +## File Template + +```markdown +--- +status: testing | complete +phase: XX-name +source: [list of SUMMARY.md files tested] +started: [ISO timestamp] +updated: [ISO timestamp] +--- + +## Current Test + + +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 + +### 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 +- UAT-002: [brief summary] (major) - Test 7 +``` + +--- + + + +**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 + +**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}` +- This section feeds directly into /gsd:plan-fix + + + + + +**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 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) + + + + +```markdown +--- +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 + +### 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 +``` + + + + +| 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 | + + diff --git a/get-shit-done/templates/uat-issues.md b/get-shit-done/templates/uat-issues.md deleted file mode 100644 index ca26ae590..000000000 --- a/get-shit-done/templates/uat-issues.md +++ /dev/null @@ -1,143 +0,0 @@ -# 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 - ---- - - -```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* -``` - - - -**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 - diff --git a/get-shit-done/workflows/verify-work.md b/get-shit-done/workflows/verify-work.md index d00196ee9..cf625dfe2 100644 --- a/get-shit-done/workflows/verify-work.md +++ b/get-shit-done/workflows/verify-work.md @@ -1,202 +1,352 @@ -Guide manual user acceptance testing of recently built features. Extract deliverables from SUMMARY.md, generate test checklist, guide user through each test, log issues to phase-scoped file. +Validate built features through conversational testing with persistent state. Creates UAT.md that tracks test progress, survives /clear, and feeds into /gsd:plan-fix. -The USER performs all testing — Claude generates the checklist, guides the process, and captures issues. +User tests, Claude records. One test at a time. Plain text responses. + +**Show expected, ask if reality matches.** + +Claude presents what SHOULD happen. User confirms or describes what's different. +- "yes" / "y" / "next" / empty → pass +- Anything else → logged as issue, severity inferred + +No Pass/Fail buttons. No severity questions. Just: "Here's what should happen. Does it?" + + + + - -**Determine what to test:** - -If $ARGUMENTS provided: -- Parse as phase number (e.g., "4") or plan number (e.g., "04-02") -- Find corresponding SUMMARY.md file(s) - -If no arguments: -- Find most recently modified SUMMARY.md + +**First: Check for active UAT sessions** ```bash -find .planning/phases -name "*SUMMARY.md" -type f -exec ls -lt {} + | head -5 +find .planning/phases -name "*-UAT.md" -type f 2>/dev/null | head -5 ``` -Read the SUMMARY.md to understand what was built. +**If active sessions exist AND no $ARGUMENTS provided:** + +Read each file's frontmatter (status, phase) and Current Test section. + +Display inline: + +``` +## Active UAT Sessions + +| # | Phase | Status | Current Test | Progress | +|---|-------|--------|--------------|----------| +| 1 | 04-comments | testing | 3. Reply to Comment | 2/6 | +| 2 | 05-auth | testing | 1. Login Form | 0/4 | + +Reply with a number to resume, or provide a phase number to start new. +``` + +Wait for user response. + +- If user replies with number (1, 2) → Load that file, go to `resume_from_file` +- If user replies with phase number → Treat as new session, go to `create_uat_file` + +**If active sessions exist AND $ARGUMENTS provided:** + +Check if session exists for that phase. If yes, offer to resume or restart. +If no, continue to `create_uat_file`. + +**If no active sessions AND no $ARGUMENTS:** + +``` +No active UAT sessions. + +Provide a phase number to start testing (e.g., /gsd:verify-work 4) +``` + +**If no active sessions AND $ARGUMENTS provided:** + +Continue to `create_uat_file`. - + +**Find what to test:** + +Parse $ARGUMENTS as phase number (e.g., "4") or plan number (e.g., "04-02"). + +```bash +# Find phase directory +PHASE_DIR=$(ls -d .planning/phases/${PHASE_ARG}* 2>/dev/null | head -1) + +# Find SUMMARY files +ls "$PHASE_DIR"/*-SUMMARY.md 2>/dev/null +``` + +Read each SUMMARY.md to extract testable deliverables. + + + **Extract testable deliverables from SUMMARY.md:** Parse for: 1. **Accomplishments** - Features/functionality added -2. **Files Created/Modified** - What changed -3. **User-facing changes** - UI, workflows, interactions +2. **User-facing changes** - UI, workflows, interactions Focus on USER-OBSERVABLE outcomes, not implementation details. +For each deliverable, create a test: +- name: Brief test name +- expected: What the user should see/experience (specific, observable) + Examples: -- "Check-in menu item added to navigation" → User can see/click Check-in in nav -- "HomePage refreshes after check-in" → After check-in, home shows updated state +- Accomplishment: "Added comment threading with infinite nesting" + → Test: "Reply to a Comment" + → Expected: "Clicking Reply opens inline composer below comment. Submitting shows reply nested under parent with visual indentation." + +Skip internal/non-observable items (refactors, type changes, etc.). - -**Generate manual test checklist:** + +**Create UAT file with all tests:** -Create structured test plan: - -``` -# User Acceptance Test: [Plan/Phase Name] - -**Scope:** [What was built - from SUMMARY.md] -**Testing:** Manual user validation - -## Pre-flight -- [ ] Application builds and runs without errors -- [ ] Application launches to expected state - -## Feature Tests - -### [Feature 1 from deliverables] -**What to test:** [User-observable behavior] -**Steps:** -1. [Specific action to take] -2. [What to look for] -3. [Expected result] - -### [Feature 2 from deliverables] -... - -## Edge Cases -- [ ] [Relevant edge case based on feature] -- [ ] [Another edge case] - -## Visual/UX Check -- [ ] UI matches expected design -- [ ] No visual glitches or layout issues -- [ ] Responsive to interactions +```bash +mkdir -p "$PHASE_DIR" ``` -Present this checklist to user. - +Build test list from extracted deliverables. - -**Guide user through each test:** - -For each test item, use AskUserQuestion: -- header: "[Feature name]" -- question: "[Test description] - Did this work as expected?" -- options: - - "Pass" — Works correctly - - "Fail" — Doesn't work as expected - - "Partial" — Works but with issues - - "Skip" — Can't test right now - -**If Pass:** Move to next test - -**If Fail or Partial:** -Follow up with AskUserQuestion: -- header: "Issue details" -- question: "What went wrong?" -- options: - - "Crashes/errors" — Application error or exception - - "Wrong behavior" — Does something unexpected - - "Missing feature" — Expected functionality not present - - "UI/visual issue" — Looks wrong but functions - - "Let me describe" — Free-form description needed - - - -**Collect and categorize issues:** - -For each failed/partial test, gather: -- Feature affected -- What went wrong (from user input) -- Severity: - - **Blocker** — Can't use the feature at all - - **Major** — Feature works but significant problem - - **Minor** — Small issue, feature still usable - - **Cosmetic** — Visual only, no functional impact - - - -**Log issues to phase-scoped file:** - -If any issues found: - -1. Create `.planning/phases/XX-name/{phase}-{plan}-ISSUES.md` if doesn't exist -2. Use template from `@~/.claude/get-shit-done/templates/uat-issues.md` -3. Add each issue: +Create file: ```markdown -### UAT-[NNN]: [Brief description] +--- +status: testing +phase: XX-name +source: [list of SUMMARY.md files] +started: [ISO timestamp] +updated: [ISO timestamp] +--- -**Discovered:** [date] during user acceptance testing -**Phase/Plan:** [phase]-[plan] that was tested -**Severity:** [Blocker/Major/Minor/Cosmetic] -**Description:** [User's description of the problem] -**Expected:** [What should have happened] -**Actual:** [What actually happened] +## Current Test + + +number: 1 +name: [first test name] +expected: | + [what user should observe] +awaiting: user response + +## Tests + +### 1. [Test Name] +expected: [observable behavior] +result: [pending] + +### 2. [Test Name] +expected: [observable behavior] +result: [pending] + +... + +## Summary + +total: [N] +passed: 0 +issues: 0 +pending: [N] +skipped: 0 + +## Issues for /gsd:plan-fix + +[none yet] ``` -**Note:** Issues go to phase-scoped file, NOT global `.planning/ISSUES.md`. This keeps UAT findings tied to the specific work being tested and enables `/gsd:plan-fix` to address them. +Write to `.planning/phases/XX-name/{phase}-UAT.md` + +Proceed to `present_test`. - -**Present test summary:** + +**Present current test to user:** + +Read Current Test section from UAT file. + +Display: ``` -# Test Results: [Plan/Phase Name] +## Test {number}: {name} -**Tests run:** [N] -**Passed:** [N] -**Failed:** [N] -**Partial:** [N] -**Skipped:** [N] +**Expected:** {expected} -## Issues Found -[List any issues with severity] - -## Verdict -[Based on results:] -- ALL PASS: "All tests passed. Feature validated." -- MINOR ISSUES: "Feature works with minor issues logged." -- MAJOR ISSUES: "Significant issues found - review before proceeding." -- BLOCKERS: "Blocking issues found - must fix before continuing." - -## Next Steps -[Based on verdict:] -- If clean: Suggest proceeding to next phase -- If issues: Suggest /gsd:plan-fix to address +Does this match what you see? ``` + +Wait for user response (plain text, no AskUserQuestion). - -**Offer next actions based on results:** + +**Process user response and update file:** -Use AskUserQuestion: -- header: "Next" -- question: "What would you like to do?" -- options (based on results): +**If response indicates pass:** +- Empty response, "yes", "y", "ok", "pass", "next", "approved", "✓" -If all passed: -- "Continue to next phase" — Proceed with confidence -- "Test more" — Run additional manual tests -- "Done" — Finish testing session +Update Tests section: +``` +### {N}. {name} +expected: {expected} +result: pass +``` -If issues found: -- "Plan fixes" — Create plan to address issues (/gsd:plan-fix) -- "Log and continue" — Issues logged, proceed anyway -- "Review issues" — Look at logged issues in detail -- "Done" — Finish testing session +**If response indicates skip:** +- "skip", "can't test", "n/a" + +Update Tests section: +``` +### {N}. {name} +expected: {expected} +result: skipped +reason: [user's reason if provided] +``` + +**If response is anything else:** +- Treat as issue description + +Infer severity from description: +- Contains: crash, error, exception, fails, broken, unusable → blocker +- Contains: doesn't work, wrong, missing, can't → major +- Contains: slow, weird, off, minor, small → minor +- Contains: color, font, spacing, alignment, visual → cosmetic +- Default if unclear: major + +Update Tests section: +``` +### {N}. {name} +expected: {expected} +result: issue +reported: "{verbatim user response}" +severity: {inferred} +``` + +Append to Issues section: +``` +- UAT-{NNN}: {brief summary from response} ({severity}) - Test {N} +``` + +**After any response:** + +Update Summary counts. +Update frontmatter.updated timestamp. + +If more tests remain → Update Current Test, go to `present_test` +If no more tests → Go to `complete_session` + + + +**Resume testing from UAT file:** + +Read the full UAT file. + +Find first test with `result: [pending]`. + +Announce: +``` +Resuming: Phase {phase} UAT +Progress: {passed + issues + skipped}/{total} +Issues found so far: {issues count} + +Continuing from Test {N}... +``` + +Update Current Test section with the pending test. +Proceed to `present_test`. + + + +**Complete testing and commit:** + +Update frontmatter: +- status: complete +- updated: [now] + +Clear Current Test section: +``` +## Current Test + +[testing complete] +``` + +Commit the UAT file: +```bash +git add ".planning/phases/XX-name/{phase}-UAT.md" +git commit -m "test({phase}): complete UAT - {passed} passed, {issues} issues" +``` + +Present summary: +``` +## UAT Complete: Phase {phase} + +| Result | Count | +|--------|-------| +| Passed | {N} | +| Issues | {N} | +| Skipped| {N} | + +[If issues > 0:] +### Issues Found + +[List from Issues section] + +--- + +Next steps: +- `/gsd:plan-fix {phase}` — Create fix plan for issues +- `/gsd:verify-work {phase}` — Re-test after fixes +- Continue to next phase + +[If issues == 0:] +All tests passed. Ready to continue. + +- `/gsd:plan-phase {next}` — Plan next phase +- `/gsd:execute-phase {next}` — Execute next phase +``` + +**Section update rules:** + +| Section | Rule | When | +|---------|------|------| +| Frontmatter.status | OVERWRITE | Start, complete | +| Frontmatter.updated | OVERWRITE | Every update | +| Current Test | OVERWRITE | Each test transition | +| Tests.{N}.result | OVERWRITE | When user responds | +| Summary | OVERWRITE | After each response | +| Issues | APPEND | When issue found | + +**Update file AFTER processing each response.** If context resets, file shows exactly where to resume. + + + +**Infer severity from user's natural language:** + +| User says | Infer | +|-----------|-------| +| "crashes", "error", "exception", "fails completely" | blocker | +| "doesn't work", "nothing happens", "wrong behavior" | major | +| "works but...", "slow", "weird", "minor issue" | minor | +| "color", "spacing", "alignment", "looks off" | cosmetic | + +Default to **major** if unclear. User can correct if needed. + +**Never ask "how severe is this?"** - just infer and move on. + + -- [ ] Test scope identified from SUMMARY.md -- [ ] Checklist generated based on deliverables -- [ ] User guided through each test via AskUserQuestion -- [ ] All test results captured (pass/fail/partial/skip) -- [ ] Any issues logged to phase-scoped ISSUES.md -- [ ] Summary presented with verdict -- [ ] User knows next steps based on results +- [ ] UAT file created with all tests from SUMMARY.md +- [ ] Tests presented one at a time with expected behavior +- [ ] User responses processed as pass/issue/skip +- [ ] Severity inferred from description (never asked) +- [ ] File updated after each response +- [ ] Can resume perfectly from any /clear +- [ ] Committed on completion +- [ ] Clear next steps based on results