Verify Built Features

Test features through conversational user acceptance testing

Overview

The /gsd:verify-work command validates that built features actually work from a user’s perspective. This is manual testing - you test each feature and report whether it works or what’s wrong.

Why Manual Verification

Automated verification (during execute-phase) checks:

• Code exists
• Tests pass
• Requirements are covered

But it can’t verify:

• User experience - Does the flow make sense?
• Visual correctness - Does it look right?
• Edge cases - Does error handling work in practice?
• Integration feel - Do pieces fit together?

Verify-work is where you use what Claude built and confirm it matches your vision.

What It Does

1. Extract Testable Deliverables

   Reads phase plans and identifies user-facing features.

2. Present Tests One-by-One

   Shows each deliverable as a yes/no question.

3. Capture Feedback

   For failures, asks what’s wrong (plain text, no interrogation).

4. Diagnose Issues

   Spawns debug agents to find root causes.

5. Create Fix Plans

   Generates verified PLAN.md files for immediate re-execution.

Output: {phase_num}-UAT.md tracking all results. If issues found: diagnosed fix plans ready for /gsd:execute-phase --gaps-only.

Command Usage

/gsd:verify-work [phase-number]

Test Specific Phase

/gsd:verify-work 2

Tests all deliverables from phase 2.

Resume Session

/gsd:verify-work

Omit phase number to:

• Resume active UAT session
• Or prompt for phase to test

Conversational Testing

Verify-work presents one test at a time:

Example Session

📋 Phase 2 UAT: User Authentication

4 deliverables to test

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✓ Test 1/4: User Registration

Can you create a new user account with email and password?

Try:
1. Navigate to /register
2. Enter email and password
3. Submit form

Does registration work? (yes/no/skip)

Response Options

yes

Feature works as expected.

> yes

✓ Test 1 passed: User Registration

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✓ Test 2/4: Login Functionality
...

no

Feature doesn’t work. GSD asks what’s wrong.

> no

What's wrong with registration?

> The form submits but shows no error when email is invalid

Got it. Diagnosing issue...

[Spawns debug agent to investigate]

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✓ Test 2/4: Login Functionality
...

skip

Can’t test right now or not important.

> skip

⊘ Test 1 skipped: User Registration

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✓ Test 2/4: Login Functionality
...

Describe Issue

Provide specific details about the problem.

> The password validation accepts "abc" which should fail

Got it. Recording issue:
Password validation too lenient - accepts weak passwords

Diagnosing...

Be specific about failures. “Doesn’t work” is vague. “Submit button does nothing when clicked” helps debug agents find the issue faster.

Automatic Diagnosis

When you report a failure, GSD:

1. Spawn Debug Agent

   Loads phase context, plan details, and execution summary.

2. Investigate Root Cause

   Examines code, tests, and configuration.

3. Identify Fix

   Determines what needs to change.

4. Create Gap Plan

   Generates a PLAN.md file marked as gap_closure: true.

Diagnosis Example

🔍 Diagnosing: Email validation not working

Investigating:
- src/app/api/auth/register/route.ts
- src/lib/validation.ts
- 02-01-SUMMARY.md

Root cause identified:
- validation.ts exports isValidEmail
- register route imports it
- BUT: route calls validateEmail (typo)
- Function exists but isn't called

Fix: Correct function name in register route

✓ Created: 02-01-GAP-validation-fix-PLAN.md

Gap Closure Plans

Fix plans are standard PLAN.md files with one difference:

---
phase: 2
plan: 1
gap_closure: true          # Marks this as a fix
parent_plan: "02-01"       # Links to original plan
---

Gap plans are executed with /gsd:execute-phase 2 --gaps-only, which runs only plans marked gap_closure: true.

UAT Output

Results are saved to {phase_num}-UAT.md:

Example: 02-UAT.md

# Phase 2 UAT: User Authentication

Tested: 2024-03-06
Status: ISSUES_FOUND

## Test Results

### ✓ Test 1: User Registration
**Status:** PASSED
**Tested:** Form accepts valid input and creates user

### ✗ Test 2: Email Validation
**Status:** FAILED
**Issue:** Form submits without validating email format
**Diagnosis:** Function name typo in register route
**Fix Plan:** 02-01-GAP-validation-fix-PLAN.md

### ✓ Test 3: Password Hashing
**Status:** PASSED
**Tested:** Passwords stored as bcrypt hashes

### ⊘ Test 4: Rate Limiting
**Status:** SKIPPED
**Reason:** Requires load testing tools

## Summary
- Passed: 2
- Failed: 1
- Skipped: 1

## Next Steps
1. Run `/gsd:execute-phase 2 --gaps-only` to fix issues
2. Re-run `/gsd:verify-work 2` to confirm fixes
3. Once all tests pass, proceed to next phase

Session Persistence

UAT sessions are saved after each test:

✓ Test 2/4 complete

Session saved. You can:
- Continue testing
- Stop and resume later with /gsd:verify-work 2
- Review results so far in 02-UAT.md

If you stop mid-session, the next run resumes where you left off:

📋 Resuming Phase 2 UAT

Previous session:
- Test 1: PASSED ✓
- Test 2: FAILED ✗
- Test 3: Not tested
- Test 4: Not tested

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✓ Test 3/4: Password Hashing
...

Fixing Issues

After UAT identifies problems:

1. Review Fix Plans

   ls .planning/*GAP*.md
   

   Check that fix plans make sense before executing.

2. Execute Gap Plans

   /gsd:execute-phase 2 --gaps-only
   

   Runs only the fix plans, skips already-completed work.

3. Re-Test

   /gsd:verify-work 2
   

   Test again to confirm fixes worked.

4. Pass All Tests

   Once everything passes:

   ✓ Phase 2 UAT complete
   
   All tests passed:
   - User Registration ✓
   - Email Validation ✓
   - Password Hashing ✓
   - Rate Limiting ✓
   
   Phase 2 verified and ready.
   
   Next steps:
   - /gsd:discuss-phase 3 - Start next phase
   - /gsd:complete-milestone - If all phases done
   

Example Full Session

1. Start verification

   /gsd:verify-work 2
   

   📋 Phase 2 UAT: User Authentication
   
   Extracting deliverables from plans...
   Found 4 testable features
   
2. Test 1 - Success

   ✓ Test 1/4: User Registration
   
   Can you create a new account?
   Try: Navigate to /register, enter email/password, submit
   
   > yes
   
   ✓ Test 1 passed
   
3. Test 2 - Failure

   ✓ Test 2/4: Email Validation
   
   Does the form reject invalid emails?
   Try: Enter "notanemail", submit
   
   > no, it accepts invalid emails
   
   Diagnosing issue...
   
   Root cause: Function name typo in register route
   ✓ Created: 02-01-GAP-validation-fix-PLAN.md
   
   ✗ Test 2 failed (fix plan ready)
   
4. Test 3 - Success

   ✓ Test 3/4: Password Security
   
   Are passwords hashed in the database?
   Try: Check DB after registration
   
   > yes
   
   ✓ Test 3 passed
   
5. Test 4 - Skip

   ✓ Test 4/4: Rate Limiting
   
   Does rate limiting block excessive requests?
   Try: Make 50+ requests in 10 seconds
   
   > skip (don't have load testing setup)
   
   ⊘ Test 4 skipped
   
6. Session Complete

   ✓ Phase 2 UAT complete
   
   Results:
   - Passed: 2
   - Failed: 1
   - Skipped: 1
   
   Issues found:
   - Email validation not working
   
   Next steps:
   1. /gsd:execute-phase 2 --gaps-only (fix issue)
   2. /gsd:verify-work 2 (re-test)
   
7. Fix and Re-Test

   /gsd:execute-phase 2 --gaps-only
   

   🌊 Executing gap closure plans for Phase 2
   
   Plans:
   - 02-01-GAP-validation-fix-PLAN.md (1 task)
   
   ✓ Fixed: Email validation function name
   ✓ Committed: fix(02-01): correct validation function name
   

   /gsd:verify-work 2
   

   ✓ Test 2/4: Email Validation
   
   Does the form reject invalid emails?
   
   > yes
   
   ✓ Test 2 passed
   
   All tests now passing!
   Phase 2 fully verified.
   

Tips

Test immediately after execution. Don’t wait until all phases are done - catch issues early.

Focus on user workflows. Don’t test individual functions. Test complete features from a user’s perspective.

Use real data. Test with realistic inputs, not just “[e-mail]” and “password123”.

If diagnosis repeatedly fails to find the issue, provide more detail: error messages, console output, screenshots, or exact steps to reproduce.

When to Skip Verification

You might skip verify-work if:

• Phase is purely technical (refactoring, optimization)
• Automated tests cover everything adequately
• You’re prototyping rapidly and will test later
• Phase deliverables aren’t user-facing

Even if you skip, UAT findings are valuable before shipping. Consider running verify-work before /gsd:complete-milestone.

Next Steps

After verification:

Next Phase

Start discussing and planning the next phase

Complete Milestone

If all phases verified, complete the milestone