feat(skills): add verification-before-completion skill

packages/rules/.ai-rules/skills/verification-before-completion/SKILL.md

@@ -0,0 +1,234 @@
+---
+name: verification-before-completion
+description: Use when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims
+user-invocable: true
+---
+
+# Verification Before Completion
+
+## Overview
+
+Claiming success without evidence is guessing. "It should work" is not verification.
+
+**Core principle:** ALWAYS run verification commands and confirm output before claiming work is complete. Evidence before assertions.
+
+**Violating the letter of these checks is violating the spirit of quality.**
+
+## The Iron Law
+
+```
+NO SUCCESS CLAIMS WITHOUT RUNNING VERIFICATION COMMANDS
+```
+
+If you haven't seen passing output with your own eyes, you cannot claim it works.
+
+**No exceptions:**
+- Don't say "tests should pass" — run them
+- Don't say "build looks fine" — build it
+- Don't say "no lint errors" — lint it
+- Don't say "changes look good" — diff them
+
+## When to Use
+
+**Always, before:**
+- Claiming work is "done" or "complete"
+- Committing code
+- Creating pull requests
+- Closing issues
+- Reporting success to teammates
+- Moving to the next task
+
+**Use this ESPECIALLY when:**
+- Under time pressure (rushing guarantees missed issues)
+- Changes seem trivial ("just a typo" can break builds)
+- You've made multiple changes across files
+- Refactoring existing code
+- Fixing bugs (verify the fix AND no regressions)
+
+**Don't skip when:**
+- Change seems too small to break anything (small changes break things)
+- You're confident it works (confidence ≠ evidence)
+- You "already tested manually" (manual ≠ systematic)
+- CI will catch it (catch it NOW, not after push)
+
+## The Four Phases
+
+You MUST complete all four phases before claiming completion. Order matters.
+
+### Phase 1: Test Execution
+
+**Run ALL relevant tests, not just the ones you think matter.**
+
+```bash
+# Run tests for affected area
+npm test -- --coverage path/to/affected/
+# OR
+yarn test path/to/affected/
+
+# Run full test suite if changes are cross-cutting
+npm test
+```
+
+**Verify:**
+- [ ] All tests pass (zero failures)
+- [ ] No test warnings or errors in output
+- [ ] Coverage hasn't decreased
+- [ ] New code has corresponding tests
+- [ ] No skipped tests you forgot to unskip
+
+**Test fails?** Fix it. Do NOT proceed to Phase 2.
+
+**No tests exist?** Write them first. Untested code is unverified code.
+
+### Phase 2: Build Verification
+
+**Confirm the project compiles and builds without errors.**
+
+```bash
+# TypeScript projects
+npx tsc --noEmit
+
+# Build the project
+npm run build
+# OR
+yarn build
+```
+
+**Verify:**
+- [ ] Zero TypeScript errors
+- [ ] Zero build errors
+- [ ] Zero build warnings (or only pre-existing ones)
+- [ ] Output artifacts are generated correctly
+
+**Build fails?** Fix it. Do NOT proceed to Phase 3.
+
+**"It builds on my machine"** is not verification. Run the actual build command.
+
+### Phase 3: Lint and Quality Check
+
+**Run linters and formatters to catch style and quality issues.**
+
+```bash
+# Lint
+npm run lint
+# OR
+npx eslint src/
+
+# Format check
+npm run format:check
+# OR
+npx prettier --check .
+```
+
+**Verify:**
+- [ ] Zero lint errors
+- [ ] Zero formatting issues
+- [ ] No new warnings introduced
+- [ ] Pre-commit hooks will pass
+
+**Lint fails?** Fix it. Do NOT proceed to Phase 4.
+
+**Don't disable rules** to make lint pass. Fix the code.
+
+### Phase 4: Diff Review
+
+**Review your own changes before anyone else sees them.**
+
+```bash
+# Review all changes
+git diff
+
+# Review staged changes
+git diff --cached
+
+# Check for untracked files
+git status
+```
+
+**Verify:**
+- [ ] No debug code (console.log, debugger, TODO hacks)
+- [ ] No commented-out code
+- [ ] No unintended file changes
+- [ ] No secrets, credentials, or API keys
+- [ ] No large binary files accidentally staged
+- [ ] Commit scope matches intent (no unrelated changes)
+
+**Found issues?** Fix them. Do NOT commit.
+
+**"I'll clean it up later"** — No. Clean it up now.
+
+## The Verification Report
+
+After completing all four phases, summarize evidence:
+
+```
+## Verification Complete
+
+- Tests: ✅ X passed, 0 failed (Y% coverage)
+- Build: ✅ Clean compilation, zero errors
+- Lint:  ✅ No errors, no new warnings
+- Diff:  ✅ Reviewed, no debug code or secrets
+```
+
+**Only after this report can you claim work is complete.**
+
+## Red Flags — STOP and Verify
+
+If you catch yourself thinking:
+
+| Thought | Reality |
+|---------|---------|
+| "Tests should pass" | Run them. "Should" isn't evidence. |
+| "I only changed one line" | One line can break everything. Verify. |
+| "CI will catch it" | Catch it now. Don't waste CI time. |
+| "I already tested manually" | Manual testing is incomplete. Run automated checks. |
+| "Build was fine last time" | Your changes may have broken it. Build again. |
+| "Lint is too strict" | Fix code, don't disable rules. |
+| "I'll review the diff later" | Review now. Later never comes. |
+| "It's just a docs change" | Docs can have broken links, bad formatting. Verify. |
+| "Tests take too long" | Run them anyway. Slow tests > shipped bugs. |
+| "I'm confident it works" | Confidence without evidence is arrogance. |
+
+**ALL of these mean: STOP. Run the verification.**
+
+## Common Rationalizations
+
+| Excuse | Reality |
+|--------|---------|
+| "Too simple to break" | Simple changes break builds. 30-second check prevents hours of debugging. |
+| "I'll verify after commit" | Post-commit fixes require amend/revert. Verify before. |
+| "Only changed tests" | Test changes can mask real failures. Run the suite. |
+| "CI runs everything" | CI feedback is slow. Local verification is fast. Catch issues immediately. |
+| "Time pressure, ship it" | Shipping broken code creates MORE time pressure. Verify now. |
+| "Other tests are flaky" | Distinguish your failures from flaky ones. Don't hide behind noise. |
+| "Reviewer will catch it" | Reviewers miss things. Self-review catches 80% of issues. |
+| "It worked in dev" | Dev ≠ prod. Build and test in the actual target environment. |
+
+## Quick Reference
+
+| Phase | Command | Success Criteria |
+|-------|---------|------------------|
+| **1. Tests** | `npm test` | All pass, no warnings |
+| **2. Build** | `npm run build` / `tsc --noEmit` | Zero errors |
+| **3. Lint** | `npm run lint` | Zero errors, no new warnings |
+| **4. Diff** | `git diff` + `git status` | Clean, no debug code |
+
+## Integration with Other Skills
+
+- **After TDD:** Verification is the final gate after Red-Green-Refactor completes
+- **After debugging:** Verify the fix AND verify no regressions were introduced
+- **Before shipping:** This skill is the prerequisite to any commit or PR workflow
+
+**Related skills:**
+- **superpowers:test-driven-development** — For writing tests (Phase 1 input)
+- **superpowers:systematic-debugging** — For investigating failures found during verification
+
+## Final Rule
+
+```
+Evidence before assertions.
+Verification before completion.
+Output before claims.
+```
+
+No exceptions without your human partner's permission.