Skip to main content

​
Overview

The gsd:verify-work command validates built features through conversational testing with persistent state. It confirms that what Claude built actually works from your perspective—one test at a time, with plain text responses, no interrogation.

​
Usage

/gsd:verify-work [phase]

/gsd:verify-work 3

​
Parameters

​
phase
number
The phase number to verify (e.g., 1, 2, 3).
  • If provided: Tests the specific phase
  • If not provided: Checks for active sessions or prompts for phase selection

​
How It Works

The command follows a conversational testing workflow:
  1. Session Management - Creates or resumes testing session
  2. Test Presentation - Shows one test case at a time
  3. Your Response - You describe what happened (pass/fail/issue)
  4. Diagnosis (if needed) - Automatically investigates issues
  5. Fix Planning - Creates verified fix plans ready for execution
  6. State Tracking - Records all results in UAT.md
The testing is conversational—not a checklist. You describe what you see in plain language.

​
Conversational Testing

Unlike traditional UAT, this is a dialogue: System: “Try logging in with an invalid password. What happens?” You: “I see a generic error message, but it doesn’t say whether the email or password was wrong” System: Investigates code, diagnoses issue, creates fix plan
One test at a time. Plain text responses. No form filling or rigid pass/fail checkboxes.

​
Automatic Issue Handling

When you report an issue:
  1. Diagnosis - The system investigates the codebase
  2. Root Cause - Identifies what’s wrong
  3. Fix Plan - Creates a gap closure plan
  4. Verification - Validates the fix plan is executable
  5. Ready for Execution - Marked for --gaps-only mode

​
Issue to Fix Flow

You: "The error message is too generic"
  ↓
System diagnoses: Error handling in auth.ts:45 needs improvement
  ↓
Creates: 3-gap-improve-error-messages.md
  ↓
Ready for: /gsd:execute-phase 3 --gaps-only

​
Persistent State

Testing sessions persist across conversations:
  • Resume testing where you left off
  • Review previous test results
  • Track fixes across multiple cycles

​
Files Created/Modified

​
.planning/{phase_num}-UAT.md
file
Tracks all test results, issues found, and fix status for the phase
​
.planning/{phase_num}-gap-*.md
file
Gap closure plans created when issues are found (marked with gap_closure: true in frontmatter)

​
Examples

​
Verify Specific Phase

/gsd:verify-work 3
Starts or resumes verification testing for phase 3.

​
Resume Active Session

/gsd:verify-work
If you have an active testing session, it resumes automatically. Otherwise, prompts you to select a phase.

​
Complete Verification Cycle

# 1. Execute the phase
/gsd:execute-phase 3

# 2. Verify the work
/gsd:verify-work 3
# (You test features conversationally, issues are found)

# 3. Execute gap fixes
/gsd:execute-phase 3 --gaps-only

# 4. Verify again
/gsd:verify-work 3
# (Confirm fixes work)

​
Testing Best Practices

​
Be Specific About Issues

Good: “The error message says ‘Invalid credentials’ but doesn’t indicate whether it’s the email or password that’s wrong” Less Helpful: “It doesn’t work”

​
Test Real Scenarios

Good: “I tried uploading a 10MB file and got a timeout after 30 seconds” Less Helpful: “File upload seems slow”

​
Report Unexpected Behavior

Good: “After deleting an item, the list count still shows the old number until I refresh” Less Helpful: “Deleting is buggy”
The more specific you are, the better the system can diagnose and fix issues.

​
What Gets Tested

The system generates test cases based on:
  • Phase goals from ROADMAP.md
  • Implementation details from PLAN.md
  • User scenarios from REQUIREMENTS.md
  • Edge cases identified during planning

​
Success Criteria

Verification succeeds when:
  • All test cases have been executed
  • Issues have been documented and diagnosed
  • Fix plans created for all identified gaps
  • You’re satisfied with the quality
You don’t need to find zero issues. The goal is to identify what needs fixing, create plans, and iterate.

​
Workflow Gates

All workflow gates are preserved:
  • Session Management - Resume capability and state tracking
  • Test Presentation - One test at a time, conversational format
  • Diagnosis - Automatic investigation of reported issues
  • Fix Planning - Verified gap closure plans
  • Routing - Next-step suggestions

​
Next Steps

After verification: If gaps found: 
/gsd:execute-phase <phase> --gaps-only
Execute the fix plans, then verify again. If no gaps (or all fixed): 
/gsd:plan-phase <next-phase>
Move on to the next phase of your roadmap.

​
Allowed Tools

This command has access to:
  • Read - Read plans, code, and test files
  • Bash - Execute tests and commands
  • Glob - Find relevant files
  • Grep - Search codebase for issues
  • Edit - Modify UAT.md with results
  • Write - Create gap closure plans
  • Task - Delegate diagnosis to specialized agents