Skip to main content

​
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]

/gsd:verify-work 2
Tests all deliverables from phase 2.

​
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

Feature works as expected.
> yes

✓ Test 1 passed: User Registration

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

✓ Test 2/4: Login Functionality
...
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.
🔍 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:
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 “[email protected]” 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