Verify Built Features

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

Extract Testable Deliverables

Reads phase plans and identifies user-facing features.

Present Tests One-by-One

Shows each deliverable as a yes/no question.

Capture Feedback

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

Diagnose Issues

Spawns debug agents to find root causes.

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
Resume Session

/gsd:verify-work 2

Tests all deliverables from phase 2.

/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:

📋 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
no
skip
Describe Issue

Feature works as expected.

> yes

✓ Test 1 passed: User Registration

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

✓ Test 2/4: Login Functionality
...

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
...

Can’t test right now or not important.

> skip

⊘ Test 1 skipped: User Registration

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

✓ Test 2/4: Login Functionality
...

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:

Spawn Debug Agent

Loads phase context, plan details, and execution summary.

Investigate Root Cause

Examines code, tests, and configuration.

Identify Fix

Determines what needs to change.

Create Gap Plan

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

🔍 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:

# 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:

Review Fix Plans

ls .planning/*GAP*.md

Check that fix plans make sense before executing.

Execute Gap Plans

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

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

Re-Test

/gsd:verify-work 2

Test again to confirm fixes worked.

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

Start verification

/gsd:verify-work 2

📋 Phase 2 UAT: User Authentication

Extracting deliverables from plans...
Found 4 testable features

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

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)

Test 3 - Success

✓ Test 3/4: Password Security

Are passwords hashed in the database?
Try: Check DB after registration

> yes

✓ Test 3 passed

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

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)

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 “test@test.com” 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

Overview

Getting Started

Core Concepts

Workflow

Guides

Advanced

Overview

Why Manual Verification

What It Does

Command Usage

Conversational Testing

Response Options

Automatic Diagnosis

Gap Closure Plans

UAT Output

Session Persistence

Fixing Issues

Example Full Session

Tips

When to Skip Verification

Next Steps

Next Phase

Complete Milestone

​Overview

​Why Manual Verification

​What It Does

​Command Usage

​Conversational Testing

​Response Options

​Automatic Diagnosis

​Gap Closure Plans

​UAT Output

​Session Persistence

​Fixing Issues

​Example Full Session

​Tips

​When to Skip Verification

​Next Steps

Next Phase

Complete Milestone

Overview

Why Manual Verification

What It Does

Command Usage

Conversational Testing

Response Options

Automatic Diagnosis

Gap Closure Plans

UAT Output

Session Persistence

Fixing Issues

Example Full Session

Tips

When to Skip Verification

Next Steps