| name | verification-before-completion |
| description | Use when finishing any task. Final checklist before marking complete. Ensures nothing forgotten, all tests pass, documentation updated. |
Verification Before Completion
Core Principle
Before declaring ANY work "complete" or "done", verify EVERYTHING works. This is the final gate before handoff.
When to Use This Skill
- After completing
code-review skill
- User asks "is it done?"
- BEFORE EVERY COMMIT (mandatory)
- Before creating pull request
- Before closing an issue
- Before marking a feature as complete
The Iron Laws
1. NEVER DECLARE WORK COMPLETE WITHOUT FULL VERIFICATION
Reasons:
- Ensures nothing was forgotten
- Confirms everything actually works
- Validates against original requirements
- Prevents "one more thing" scenarios
- Professional quality gate
2. NEVER COMMIT WITHOUT VERIFICATION
This skill is MANDATORY before ANY git commit.
If you find yourself typing git commit without having completed this verification checklist, STOP.
❌ FORBIDDEN:
vim src/file.js
git add .
git commit -m "fix stuff"
✅ REQUIRED:
vim src/file.js
git add .
git commit -m "fix(api): handle null values in user profile"
Authority: Professional teams NEVER commit without verification. Unverified commits cause:
- 🐛 Bugs in production
- 💥 Broken builds
- 😡 Wasted team time
- 💸 Lost customer trust
3. FRONTEND + BACKEND = FULL TEST SUITE
When changes affect both frontend and backend:
MANDATORY before commit:
- ✅ Backend tests (unit + integration)
- ✅ Frontend tests (component + integration)
- ✅ E2E tests (full user flow)
- ✅ API tests (if API changed)
Never commit if ANY test fails.
Verification Protocol
Step 1: Announce Verification
Template:
I'm using the verification-before-completion skill to perform final checks before declaring this complete.
Step 2: Requirements Verification
Check against original user request:
Original Request:
"[User's original request verbatim]"
Requirements Checklist:
✅ [Requirement 1] - Implemented and verified
✅ [Requirement 2] - Implemented and verified
✅ [Requirement 3] - Implemented and verified
Questions to ask:
- Did I do EVERYTHING the user asked for?
- Are there any "and also" or "oh and" requests I missed?
- Did the requirements change during discussion?
- Are there implied requirements I should have addressed?
Step 3: Functionality Verification
Test the complete feature end-to-end:
End-to-End Testing:
Scenario 1: [Happy path]
Steps:
1. [Action 1] → ✅ Works
2. [Action 2] → ✅ Works
3. [Action 3] → ✅ Works
Result: ✅ Complete flow works
Scenario 2: [Alternative path]
Steps:
1. [Action 1] → ✅ Works
2. [Action 2] → ✅ Works
Result: ✅ Alternative flow works
Scenario 3: [Error path]
Steps:
1. [Action 1] → ✅ Appropriate error
Result: ✅ Error handling works
Step 4: Test Verification
Verify ALL tests pass:
Test Verification:
Before running tests:
✅ Using database-backup skill (MANDATORY)
✅ Backup created: [filename]
Running complete test suite:
Command: ./scripts/safe-test.sh vendor/bin/paratest
Results:
- Total: [X] tests
- Passed: [X] tests
- Failed: 0 tests
- Duration: [time]
- Coverage: [X]%
✅ All tests pass
Running specific feature tests:
Command: ./scripts/safe-test.sh vendor/bin/paratest --filter=[Feature]
Results:
- Total: [Y] tests
- Passed: [Y] tests
- Failed: 0 tests
✅ Feature tests pass
If ANY tests fail:
❌ Tests failed - NOT ready for completion
Failed tests:
1. [Test name] - [Failure reason]
2. [Test name] - [Failure reason]
I need to fix these before declaring complete.
Step 5: Integration Verification
Verify integration with existing system:
Integration Verification:
✅ No existing functionality broken
✅ API contracts maintained (backwards compatible)
✅ Database migrations applied successfully
✅ Database migrations can be rolled back
✅ No conflicts with other features
✅ Environment variables documented
✅ Dependencies up to date
Run regression tests:
Running full test suite to ensure nothing broke:
Command: ./scripts/safe-test.sh vendor/bin/paratest
Results: ✅ [X] tests, all passed
Step 6: Documentation Verification
Verify all documentation is complete:
Documentation Checklist:
Code Documentation:
✅ PHPDoc/JSDoc comments on all public methods
✅ Complex logic has explanatory comments
✅ Type hints on all function parameters
API Documentation:
✅ OpenAPI/Swagger documentation generated
✅ All endpoints documented
✅ Request/response examples provided
✅ Authentication requirements noted
✅ Error responses documented
Project Documentation:
✅ README.md updated (if new feature/setup)
✅ CHANGELOG.md updated with changes
✅ .env.example includes new variables
✅ Migration instructions provided (if needed)
✅ Deployment notes added (if needed)
User-Facing Documentation:
✅ Usage examples provided
✅ Common use cases documented
✅ Troubleshooting section added
Step 7: Code Quality Verification
Final quality checks:
Code Quality Checklist:
Security:
✅ No SQL injection vulnerabilities
✅ No XSS vulnerabilities
✅ No hardcoded secrets
✅ Authentication/authorization correct
✅ Input validation comprehensive
✅ OWASP Top 10 checked
Performance:
✅ No N+1 query problems
✅ Appropriate database indexes
✅ Efficient algorithms used
✅ Caching implemented where needed
✅ No performance regressions
Best Practices:
✅ DRY principle followed (no duplication)
✅ SOLID principles applied
✅ Consistent naming conventions
✅ Proper error handling
✅ Logging appropriate
✅ No commented-out code
✅ No debugging statements (console.log, dd(), etc.)
Step 8: Git Verification
Verify version control state:
Git Status Check:
✅ All changes are committed
✅ Commit messages follow conventions
✅ Branch is up to date with base branch
✅ No merge conflicts
✅ .gitignore properly configured
✅ No sensitive files committed
Git log (last commits):
[Show last 3-5 commits with messages]
Step 9: Deployment Verification
Verify deployment readiness:
Deployment Checklist:
✅ Environment variables documented
✅ Database migrations are reversible
✅ No breaking changes (or documented)
✅ Rollback plan exists
✅ Health check endpoints work
✅ CI/CD pipeline passes (if configured)
Migration Commands (if needed):
1. [Command 1]
2. [Command 2]
Rollback Commands (if needed):
1. [Command 1]
2. [Command 2]
Step 10: Final Approval
Present complete verification report:
Verification Complete ✅
✅ All requirements met
✅ All tests pass ([X] tests)
✅ No regressions detected
✅ Documentation complete
✅ Code quality verified
✅ Security checked
✅ Performance validated
✅ Git state clean
✅ Deployment ready
The [feature name] is complete and ready for [deployment/merge/review].
If issues found:
Verification Found Issues ⚠️
Issues preventing completion:
1. [Critical issue 1]
2. [Critical issue 2]
I need to address these before declaring complete.
Complete Verification Checklist
Use this comprehensive checklist:
Requirements
Functionality
Testing
Integration
Documentation
Code Quality
Version Control
Deployment
Red Flags (Incomplete Work)
- ❌ "Just need to test one more thing" → Test it NOW
- ❌ "I'll document it later" → Document NOW
- ❌ Skipped tests → Fix them NOW
- ❌ "It works on my machine" → Verify in clean environment
- ❌ Uncommitted changes → Commit NOW
- ❌ "I'll fix that typo later" → Fix NOW
Common Rationalizations to Reject
- ❌ "It's good enough" → Verify it's complete
- ❌ "The user just wants it working" → Professional quality still matters
- ❌ "I'm out of time" → Better to deliver late and complete than early and broken
- ❌ "I'll fix issues if they come up" → Fix known issues NOW
- ❌ "Documentation can wait" → Document before you forget
Example Verifications
Example 1: Complete Feature
I'm using the verification-before-completion skill for the user authentication feature.
Original Request:
"Add authentication to the API with email/password login, social OAuth, and protected routes"
Requirements Checklist:
✅ Email/password registration - Implemented
✅ Email/password login - Implemented
✅ Token-based authentication - Implemented (Sanctum)
✅ Social OAuth (Google, GitHub) - Implemented (Clerk)
✅ Protected routes - Implemented (auth:sanctum middleware)
✅ Logout functionality - Implemented
End-to-End Testing:
Scenario 1: Registration and Login
1. POST /register with email/password → ✅ Returns 201, user created
2. POST /login with credentials → ✅ Returns token
3. GET /user (protected) with token → ✅ Returns user data
Scenario 2: Social OAuth
1. GET /auth/redirect/google → ✅ Redirects to Google
2. Callback returns with user → ✅ User created/logged in
3. Token issued → ✅ Works
Scenario 3: Protected Routes
1. GET /user without token → ✅ Returns 401
2. GET /user with invalid token → ✅ Returns 401
3. GET /user with valid token → ✅ Returns 200
Scenario 4: Error Handling
1. Register with invalid email → ✅ Returns 422 with validation errors
2. Login with wrong password → ✅ Returns 401 with clear message
3. Login with non-existent email → ✅ Returns 401 with clear message
Test Verification:
Before running tests:
✅ Using database-backup skill
✅ Backup created: backups/database_2025-01-06_15-30-00.sql
Running complete test suite:
Command: ./scripts/safe-test.sh vendor/bin/paratest
Results:
- Total: 127 tests
- Passed: 127 tests
- Failed: 0 tests
- Duration: 8.2s
- Coverage: 87%
✅ All tests pass
Running authentication tests specifically:
Command: ./scripts/safe-test.sh vendor/bin/paratest --filter=Authentication
Results:
- Total: 15 tests
- Passed: 15 tests
- Failed: 0 tests
✅ Feature tests pass
Integration Verification:
✅ No existing functionality broken (regression tests passed)
✅ API contracts maintained (backwards compatible)
✅ Database migrations applied: users table, personal_access_tokens table
✅ Migrations can be rolled back: php artisan migrate:rollback
✅ No conflicts with other features
✅ Environment variables: CLERK_PUBLISHABLE_KEY, CLERK_SECRET_KEY added to .env.example
✅ Dependencies: laravel/sanctum, clerk/clerk-sdk-php added
Documentation Verification:
Code Documentation:
✅ AuthController methods have comprehensive PHPDoc
✅ Complex OAuth logic has explanatory comments
✅ Type hints on all function parameters
API Documentation:
✅ OpenAPI documentation generated: /docs/api
✅ All endpoints documented:
- POST /register
- POST /login
- POST /logout
- GET /auth/redirect/{provider}
- GET /auth/callback/{provider}
✅ Request/response examples provided for each
✅ Authentication requirements: "Bearer token required for protected routes"
✅ Error responses documented (401, 422, 500)
Project Documentation:
✅ README.md updated with authentication setup section
✅ CHANGELOG.md updated:
- Added: Token-based authentication with Sanctum
- Added: Social OAuth with Clerk (Google, GitHub)
- Added: Protected route middleware
✅ .env.example includes CLERK_* variables
✅ Migration instructions in README: php artisan migrate
✅ Deployment notes: Clerk keys must be set in production
User-Facing Documentation:
✅ Usage examples in README:
- How to register a user
- How to login
- How to use tokens
- How to add social OAuth
✅ Common use cases documented
✅ Troubleshooting section added:
- Token not working → Check Sanctum middleware
- OAuth callback fails → Verify Clerk configuration
Code Quality Verification:
Security:
✅ Passwords hashed with bcrypt (Laravel default)
✅ SQL injection: Using Eloquent ORM (parameterized)
✅ XSS: No raw output, API returns JSON
✅ No hardcoded secrets (all in .env)
✅ Authentication: Sanctum properly configured
✅ Authorization: Middleware on protected routes
✅ Input validation: FormRequest classes with rules
✅ Rate limiting: 5 login attempts per minute per IP
Performance:
✅ No N+1 queries (eager loading used)
✅ Database indexes: index on users.email
✅ Token lookup optimized
✅ Caching: Not needed for auth (stateless tokens)
✅ No performance regressions
Best Practices:
✅ DRY: AuthController methods reuse validation logic
✅ SOLID: Single responsibility per method
✅ Naming: Clear, consistent (login, register, logout)
✅ Error handling: Try-catch for OAuth, clear error messages
✅ Logging: Failed login attempts logged
✅ No commented-out code
✅ No debugging statements (removed all dd(), var_dump())
Git Verification:
✅ All changes committed (3 commits)
✅ Commit messages:
- "Add Laravel Sanctum token authentication"
- "Add Clerk social OAuth integration"
- "Add authentication tests and documentation"
✅ Branch 'feature/authentication' up to date with main
✅ No merge conflicts
✅ .gitignore includes .env (secrets not committed)
✅ No sensitive files in history
Deployment Verification:
✅ Environment variables documented in .env.example
✅ Database migrations reversible:
- Rollback: php artisan migrate:rollback
- Steps: 2 migrations to rollback
✅ No breaking changes (new feature, existing routes unchanged)
✅ Rollback plan:
1. php artisan migrate:rollback --step=2
2. composer remove laravel/sanctum clerk/clerk-sdk-php
3. Remove routes from api.php
4. Remove AuthController
Migration Commands:
1. php artisan migrate
Rollback Commands:
1. php artisan migrate:rollback --step=2
---
Verification Complete ✅
✅ All requirements met (email/password + social OAuth)
✅ All tests pass (127 tests, 15 auth tests)
✅ No regressions detected
✅ Documentation complete (code, API, project, user)
✅ Code quality verified (security, performance, best practices)
✅ Security checked (OWASP Top 10)
✅ Performance validated (no N+1, proper indexes)
✅ Git state clean (3 commits, good messages)
✅ Deployment ready (migrations, rollback plan)
The user authentication feature is complete and ready for deployment/merge.
Example 2: Issues Found
I'm using the verification-before-completion skill for the activity logging feature.
Original Request:
"Track user activity in a database table including IP address and user agent"
Requirements Checklist:
✅ Activity logging database table
✅ Logs user registration
✅ Logs user login
✅ Logs user logout
✅ Captures IP address
✅ Captures user agent
End-to-End Testing:
✅ User registration creates log entry with IP and user agent
✅ User login creates log entry
✅ User logout creates log entry
Test Verification:
Before running tests:
✅ Using database-backup skill
✅ Backup created
Running tests:
❌ FAILED - 2 test failures
Failed tests:
1. ActivityLogTest::test_logging_includes_user_agent
- Expected: User agent to be captured
- Actual: user_agent column is NULL
- Reason: ActivityLogger not capturing user agent correctly
2. ActivityLogTest::test_user_can_view_own_activity
- Expected: GET /user/activity returns activity logs
- Actual: 404 Not Found
- Reason: Forgot to implement the viewing endpoint
Verification Found Issues ⚠️
Critical Issues (preventing completion):
1. User agent not being captured
- Tests expect it, code doesn't capture it
- Fix: Update ActivityLogger to use $request->userAgent()
2. Missing endpoint to view activity logs
- User probably wants to see their activity
- This is an implied requirement
- Fix: Add GET /user/activity endpoint
I need to fix these issues before declaring complete.
After fixing:
Fixed issues:
✅ Updated ActivityLogger to capture user agent correctly
✅ Added GET /user/activity endpoint
✅ Added test for new endpoint
✅ All tests now pass (18 tests)
Re-running verification:
✅ All requirements met (including implied requirement)
✅ All tests pass
✅ End-to-end testing successful
✅ Documentation updated
Verification Complete ✅ - Activity logging is now complete and ready.
Integration with Other Skills
Before verification-before-completion: Use code-review skill
After verification-before-completion: Ready to commit/deploy
If issues found: Fix and re-verify
Authority
This skill is based on:
- Software engineering best practice: Quality gates
- Professional standard: Definition of "done"
- Agile methodology: Acceptance criteria
- Empirical evidence: Final verification catches 40% of remaining issues
Social Proof: Professional teams have explicit "definition of done" checklists. No code is "complete" without verification.
Your Commitment
Before using this skill, confirm:
Bottom Line: "Complete" means fully verified, tested, documented, and ready to deploy. Never declare done without proving it's done.
