--- name: better-coding-verify description: "Verify completion claims with fresh evidence before saying done, fixed, passing, or ready to merge — the evidence gate for every task. MUST be used before claiming any work is complete, before committing, pushing, creating a PR, or moving to the next task — even if the user does not ask for verification. Enforces the Gate Function: identify the proving command, run it, read the full output, then claim with evidence attached. Also finishes the branch: merge, PR, keep, or discard. Trigger: /better-coding-verify" metadata: version: "2.12.0" license: Apache-2.0 --- # Better Coding Verify The skill that sits between "I think it's done" and "it's done." A capable agent will declare success based on having written code, not on having verified it works. This skill enforces the discipline that every completion claim is backed by fresh evidence — a command that was actually run, with output that was actually read. **Primary objective:** no completion claim without fresh verification evidence. The agent runs the verification command, reads the full output, and only then states the result — with the evidence attached. --- ## Activation Begin the first response after loading with exactly this line: ▸ better-coding-verify active — evidence before claims, always Emit it once, then proceed. --- ## The Iron Law ``` NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE ``` If the verification command has not been run in this message, the claim cannot be made. "Should work" is not evidence. "Tests should pass" is not evidence. Previous runs are not evidence. The agent's own confidence is not evidence. **Violating the letter of this rule is violating the spirit of this rule.** --- ## The Gate Function ``` BEFORE claiming any status or expressing satisfaction: 1. IDENTIFY: What command proves this claim? 2. RUN: Execute the FULL command (fresh, complete) 3. READ: Full output, check exit code, count failures 4. VERIFY: Does output confirm the claim? - If NO: State actual status with evidence - If YES: State claim WITH evidence 5. ONLY THEN: Make the claim Skip any step = lying, not verifying ``` --- ## Evidence Requirements Per Claim Type | Claim | Required evidence | Not sufficient | |-------|-------------------|----------------| | "Tests pass" | Test command output: 0 failures | Previous run, "should pass" | | "Linter clean" | Linter output: 0 errors | Partial check, extrapolation | | "Build succeeds" | Build command: exit 0 | Linter passing, logs look good | | "Bug fixed" | Test of original symptom: passes | Code changed, assumed fixed | | "Regression test works" | Red-green cycle verified | Test passes once | | "Agent completed" | VCS diff shows changes | Agent reports "success" | | "Requirements met" | Line-by-line checklist vs spec | Tests passing | | "Type check passes" | Type checker output: 0 errors | Build succeeding | | "No regressions" | Full suite run: 0 new failures | New tests only | | "Feature works end-to-end" | Ran the actual app and observed correct behaviour (CLI output / driven UI / browser screenshot) | Unit tests passing | | "Performance unchanged" | Benchmark/timing output before vs after | "Feels fast enough" | | "Security scan clean" | Scanner output: 0 new findings | Scan not run | | "Docs in sync" | Docs updated in the same change (diff) | "Will update later" | ### Regression test verification A regression test that passes once proves nothing. It must be red-green verified: ``` 1. Write the regression test 2. Run it → it PASSES (with the fix in place) 3. Revert the fix 4. Run it → it MUST FAIL (proving the test catches the bug) 5. Restore the fix 6. Run it → it PASSES again ``` If the test passes without the fix, the test does not test the right thing. --- ## Red Flags — STOP - Using "should", "probably", "seems to", "I think" - Expressing satisfaction before verification ("Great!", "Perfect!", "Done!") - About to commit/push/PR without verification - Trusting a subagent's "success" report without checking the VCS diff - Relying on partial verification (ran unit tests but not integration tests) - Thinking "just this once" — this is the most common rationalization - Any wording implying success without having run the verification command --- ## Rationalization Prevention | Excuse | Reality | |--------|---------| | "Should work now" | RUN the verification command | | "I'm confident" | Confidence is not evidence | | "Just this once" | No exceptions — this is how bugs ship | | "Linter passed" | Linter is not compiler, not test suite | | "Agent said success" | Verify independently — check the VCS diff | | "I'm tired, let's wrap up" | Exhaustion is not an excuse for false claims | | "Partial check is enough" | Partial proves nothing about the whole | | "Different words, so the rule doesn't apply" | Spirit over letter — any success implication counts | | "The code looks correct" | Looking is not running. Run it. | | "I ran it earlier in this session" | Stale evidence. Run it again now. | --- ## Verification Hierarchy Use the strongest available verification for each claim: 1. **Automated tests** (unit/integration/e2e) — strongest 2. **Type check / static analysis** — catches type errors and patterns 3. **Build** — catches compilation and bundling errors 4. **Linter** — catches style and common mistakes 5. **Manual verification** — last resort; state why automated verification is impossible If tests are impossible in this context, state the reason explicitly and give an alternative means of verification. Do not silently skip verification. **Passing unit tests are not proof the feature works.** A capable agent makes changes and never confirms the feature works end-to-end. For anything user-facing or integrated, verify by running the actual application — drive the UI (or screenshot it and compare to the intended design), hit the real endpoint, or run the real CLI command — not only the test suite. Show the observed behaviour as evidence. --- ## Completion Report After verification, report in this format: ``` Verification: Tests: [command] → [actual output, e.g. "47 passed, 0 failed in 2.1s"] Lint: [command] → [actual output, e.g. "0 errors, 2 warnings"] Build: [command] → [actual output, e.g. "exit 0, 1.2s"] Type check:[command] → [actual output, e.g. "0 errors"] Requirements checklist: [x] Requirement 1 from spec — verified by test X [x] Requirement 2 from spec — verified by test Y [ ] Requirement 3 from spec — NOT YET VERIFIED (explain) Known limitations: - [anything not covered] Remaining risks: - [anything not verified by automated tests] ``` If any requirement is unchecked, the task is not complete. State it honestly. --- ## Finishing the Branch After verification passes, present integration options: ### Step 1: Verify tests (already done above) If tests fail, stop. Do not proceed to integration. ### Step 2: Present options ``` Implementation complete. All verification passed. What would you like to do? 1. Merge back to [base-branch] locally 2. Push and create a Pull Request 3. Keep the branch as-is (I'll handle it later) 4. Discard this work ``` ### Step 3: Execute choice - **Merge locally:** checkout base, pull, merge feature, run tests on merged result, delete feature branch. - **Push and PR:** push branch, create PR with description written from the spec (not from the commit messages). - **Keep as-is:** report branch name and current state. - **Discard:** confirm first (list commits that will be lost), then force-delete branch. ### PR description Write the PR description from the spec, not from commit messages: ``` ## What [One paragraph from the spec's problem statement] ## Why [One paragraph from the spec's motivation] ## How [2-3 sentences from the plan's architecture] ## Verification - Tests: [command] → [output] - Lint: [command] → [output] - Build: [command] → [output] ## Checklist - [x] Spec requirements met (see verification report) - [x] Tests added/updated and passing - [x] No regressions in existing suite - [x] Code reviewed via /better-coding-review ``` --- ## When To Apply **ALWAYS before:** - Any variation of success/completion claims - Any expression of satisfaction - Any positive statement about work state - Committing, PR creation, task completion - Moving to the next task - Delegating to subagents **The rule applies to:** - Exact phrases ("done", "fixed", "passing") - Paraphrases and synonyms ("wrapped up", "good to go", "ships") - Implications of success ("the feature is ready") - ANY communication suggesting completion or correctness --- ## Terminal States After verification and branch finishing: - If **all checks pass** → present integration options (merge/PR/keep/discard) - If **checks fail** → do NOT claim completion. State the failure with evidence. Invoke `/better-coding-debug` if the failure is a bug. - If **requirements unmet** → state which requirements are not yet verified. Do not claim partial completion as full completion. - If **more packages remain in the plan** → the next package starts with its step 0: re-invoke `/better-coding-workflow` (+ `/better-coding-frontend` for UI) before any code — do not assume it is still loaded. - After **merge/PR** → task chain complete. The next task starts fresh with `/better-coding-orient`. --- ## Relationship to the other skills - `/better-coding-orient` — routes to this skill as the final step in every non-trivial task chain. - `/better-coding-workflow` — produces the code this skill verifies. The workflow's own "verify with evidence" section is a lightweight version; this skill is the full gate for completion claims and branch finishing. - `/better-coding-review` — reviews code quality; this skill verifies functional correctness. Both are needed: review catches what tests cannot, tests catch what review cannot. - `/better-coding-debug` — invoked when verification reveals a failure. Debug finds the root cause; return here to re-verify after the fix. - `/better-coding-plan` — the spec from plan is the checklist this skill verifies against ("requirements met" = line-by-line check vs spec). - `/better-coding-audit` — for security-sensitive tasks, audit runs before this skill; this skill verifies audit findings are addressed.