Verification Before Complete

A disciplined skill for verifying that work is genuinely complete before claiming it. Covers verification checklists, evidence collection, common shortcuts to avoid, and establishing a culture of rigor in software delivery.

When to Use This Skill

Choose this skill when:

• Finishing a feature and need to verify it's truly done
• About to mark a ticket or task as complete
• Preparing a pull request for review
• Deploying changes to production
• Handing off work to another team member

Consider alternatives when:

• Writing tests → use a testing patterns skill
• Reviewing others' code → use a code review skill
• Setting up CI/CD checks → use a DevOps skill
• Debugging issues → use a debugging skill

Quick Start

Copy
# Verification Checklist

## Before Claiming "Done":
1. [ ] Code compiles/builds without errors or warnings
2. [ ] All existing tests pass (not just new tests)
3. [ ] New code has appropriate test coverage
4. [ ] Manually tested the happy path end-to-end
5. [ ] Tested at least 2 edge cases
6. [ ] No console.log/debug statements left
7. [ ] No hardcoded values that should be configurable
8. [ ] Error states handled and shown to users
9. [ ] Changes work in all targeted environments
10. [ ] Documentation updated if behavior changed

Core Concepts

Verification vs Assumption

Assumption (Risky)	Verification (Reliable)
"I think it works"	"I ran it and confirmed output matches expected"
"Tests should pass"	"I ran the full test suite and all 247 tests pass"
"It works locally"	"I tested in staging with production-like config"
"The refactor is safe"	"I verified all callers still work correctly"
"Dependencies are fine"	"I built from clean install and everything resolves"

Evidence Collection Pattern

Copy
# Verification Evidence Template

## Feature: User password reset
## Date: 2024-01-15
## Verified by: @developer

### Build Verification
- Build command: `npm run build` → SUCCESS (0 errors, 0 warnings)
- Test suite: `npm test` → 247 passed, 0 failed, 0 skipped

### Functional Verification
- [ ] Reset email sent with valid token
- [ ] Token expires after 24 hours
- [ ] Invalid token shows error message
- [ ] Password updated in database
- [ ] User can login with new password
- [ ] Old password no longer works

### Edge Cases Verified
- [ ] Token used twice → shows "already used" error
- [ ] Expired token → shows "expired" error
- [ ] Empty password → validation error
- [ ] SQL injection in email field → properly escaped

### Cross-Browser (if applicable)
- [ ] Chrome: ✅
- [ ] Firefox: ✅
- [ ] Safari: ✅
- [ ] Mobile Safari: ✅

Common Completeness Gaps

Copy
# Things developers forget to verify:

## Data Layer
- Database migrations run forward AND backward
- Indexes added for new query patterns
- Data backfill script tested on production-size dataset

## API Layer
- Error responses return correct status codes
- Rate limiting applies to new endpoints
- Authentication/authorization checked

## UI Layer
- Loading states during async operations
- Error states with retry option
- Empty states when no data exists
- Responsive layout on mobile
- Keyboard accessibility

## Operations
- Logging sufficient for debugging
- Monitoring/alerts for new failure modes
- Feature flag or rollback plan ready

Configuration

Parameter	Type	Default	Description
checklistLevel	string	'standard'	Checklist: minimal, standard, or thorough
evidenceRequired	boolean	true	Require evidence for each verification
mandatoryChecks	string[]	['build', 'test']	Non-skippable verification steps
environmentChecks	string[]	['local', 'staging']	Required test environments
reviewerVerification	boolean	true	Reviewer must also verify
automatedChecks	boolean	true	Run automated checks as part of verification

Best Practices

1. Run the full test suite, not just the tests you wrote — Your changes might break tests in seemingly unrelated areas. A green checkmark on the full suite is the minimum bar for claiming completeness.

2. Test with a clean build, not your development cache — rm -rf node_modules && npm ci && npm run build catches dependency issues that incremental builds hide. If it doesn't build clean, it's not done.

3. Verify error paths with the same rigor as happy paths — Type an invalid email, submit an empty form, disconnect the network during a save. If error handling isn't verified, it's likely broken.

4. Show evidence, don't just claim success — "It works" is an opinion. "Build succeeded with 0 warnings, 247 tests pass, manual test screenshots attached" is evidence. Evidence enables others to trust and build on your work.

5. Verify from the user's perspective, not just the code — Reading the code and seeing it looks correct is not verification. Open the browser, click the buttons, submit the form, check the database. The code might look right but behave wrong.

Common Issues

"It worked on my machine" fails in production — Local development has different configs, data volumes, and timing. Verify in an environment that mirrors production: same database engine, same env vars, similar data volume.

Refactoring breaks callers not covered by tests — After refactoring a function signature, search the entire codebase for all callers. grep -r "functionName" finds usages that tests don't cover. Verify each caller passes the correct arguments.

Last-minute changes bypass verification — A "small fix" before merge often introduces bugs because it skips the full verification cycle. Every change, no matter how small, goes through the same checklist. Small changes cause big outages.