evidence-verification

Evidence-Based Verification Skill

Version: 1.0.0 Type: Quality Assurance Auto-activate: Code review, task completion, production deployment

Overview

This skill teaches agents how to collect and verify evidence before marking tasks complete. Inspired by production-grade development practices, it ensures all claims are backed by executable proof: test results, coverage metrics, build success, and deployment verification.

Key Principle: Show, don't tell. No task is complete without verifiable evidence.

When to Use This Skill

Auto-Activate Triggers

• Completing code implementation
• Finishing code review
• Marking tasks complete in Squad mode
• Before agent handoff
• Production deployment verification

Manual Activation

• When user requests "verify this works"
• Before creating pull requests
• During quality assurance reviews
• When troubleshooting failures

Core Concepts

1. Evidence Types

Test Evidence

• Exit code (must be 0 for success)
• Test suite results (passed/failed/skipped)
• Coverage percentage (if available)
• Test duration

Build Evidence

• Build exit code (0 = success)
• Compilation errors/warnings
• Build artifacts created
• Build duration

Deployment Evidence

• Deployment status (success/failed)
• Environment deployed to
• Health check results
• Rollback capability verified

Code Quality Evidence

• Linter results (errors/warnings)
• Type checker results
• Security scan results
• Accessibility audit results

2. Evidence Collection Protocol

## Evidence Collection Steps

1. **Identify Verification Points**
   - What needs to be proven?
   - What could go wrong?
   - What does "complete" mean?

2. **Execute Verification**
   - Run tests
   - Run build
   - Run linters
   - Check deployments

3. **Capture Results**
   - Record exit codes
   - Save output snippets
   - Note timestamps
   - Document environment

4. **Store Evidence**
   - Add to shared context
   - Reference in task completion
   - Link to artifacts

3. Verification Standards

Minimum Evidence Requirements:

• ✅ At least ONE verification type executed
• ✅ Exit code captured (0 = pass, non-zero = fail)
• ✅ Timestamp recorded
• ✅ Evidence stored in context

Production-Grade Requirements:

• ✅ Tests run with exit code 0
• ✅ Coverage >70% (or project standard)
• ✅ Build succeeds with exit code 0
• ✅ No critical linter errors
• ✅ Security scan passes

Evidence Collection Templates

Template 1: Test Evidence

Use this template when running tests:

## Test Evidence

**Command:** `npm test` (or equivalent)
**Exit Code:** 0 ✅ / non-zero ❌
**Duration:** X seconds
**Results:**
- Tests passed: X
- Tests failed: X
- Tests skipped: X
- Coverage: X%

**Output Snippet:**

[First 10 lines of test output]

**Timestamp:** YYYY-MM-DD HH:MM:SS
**Environment:** Node vX.X.X, OS, etc.

Template 2: Build Evidence

Use this template when building:

## Build Evidence

**Command:** `npm run build` (or equivalent)
**Exit Code:** 0 ✅ / non-zero ❌
**Duration:** X seconds
**Artifacts Created:**
- dist/bundle.js (XXX KB)
- dist/styles.css (XXX KB)

**Errors:** X
**Warnings:** X

**Output Snippet:**

[First 10 lines of build output]

**Timestamp:** YYYY-MM-DD HH:MM:SS

Template 3: Code Quality Evidence

Use this template for linting and type checking:

## Code Quality Evidence

**Linter:** ESLint / Ruff / etc.
**Command:** `npm run lint`
**Exit Code:** 0 ✅ / non-zero ❌
**Errors:** X
**Warnings:** X

**Type Checker:** TypeScript / mypy / etc.
**Command:** `npm run typecheck`
**Exit Code:** 0 ✅ / non-zero ❌
**Type Errors:** X

**Timestamp:** YYYY-MM-DD HH:MM:SS

Template 4: Combined Evidence Report

Use this comprehensive template for task completion:

## Task Completion Evidence

### Task: [Task description]
### Agent: [Agent name]
### Completed: YYYY-MM-DD HH:MM:SS

### Verification Results

| Check | Command | Exit Code | Result |
|-------|---------|-----------|--------|
| Tests | `npm test` | 0 | ✅ 45 passed, 0 failed |
| Build | `npm run build` | 0 | ✅ Bundle created (234 KB) |
| Linter | `npm run lint` | 0 | ✅ No errors, 2 warnings |
| Types | `npm run typecheck` | 0 | ✅ No type errors |

### Coverage
- Statements: 87%
- Branches: 82%
- Functions: 90%
- Lines: 86%

### Evidence Files
- Test output: `.claude/quality-gates/evidence/tests-2025-XX-XX.log`
- Build output: `.claude/quality-gates/evidence/build-2025-XX-XX.log`

### Conclusion
All verification checks passed. Task ready for review.

Step-by-Step Workflows

Workflow 1: Code Implementation Verification

When: After writing code for a feature or bug fix

Steps:

1. Save all files - Ensure changes are written

1. Run tests

``bash npm test # or: pytest, cargo test, go test, etc. ``

• Capture exit code
• Note passed/failed counts
• Record coverage if available

1. Run build (if applicable)

``bash npm run build # or: cargo build, go build, etc. ``

• Capture exit code
• Note any errors/warnings
• Verify artifacts created

1. Run linter

``bash npm run lint # or: ruff check, cargo clippy, golangci-lint run ``

• Capture exit code
• Note errors/warnings

1. Run type checker (if applicable)

``bash npm run typecheck # or: mypy, tsc --noEmit ``

• Capture exit code
• Note type errors

1. Document evidence
2. Use Template 4 (Combined Evidence Report)
3. Add to shared context under quality_evidence
4. Reference in task completion message

1. Mark task complete (only if all evidence passes)

Workflow 2: Code Review Verification

When: Reviewing another agent's code or user's PR

Steps:

1. Read the code changes

1. Verify tests exist
2. Are there tests for new functionality?
3. Do tests cover edge cases?
4. Are existing tests updated?

1. Run tests
2. Execute test suite
3. Verify exit code 0
4. Check coverage didn't decrease

1. Check build
2. Ensure project still builds
3. No new build errors

1. Verify code quality
2. Run linter
3. Run type checker
4. Check for security issues

1. Document review evidence
2. Use Template 3 (Code Quality Evidence)
3. Note any issues found
4. Add to context

1. Approve or request changes
2. Approve only if all evidence passes
3. If issues found, document them with evidence

Workflow 3: Production Deployment Verification

When: Deploying to production or staging

Steps:

1. Pre-deployment checks
2. All tests pass (exit code 0)
3. Build succeeds
4. No critical linter errors
5. Security scan passes

1. Execute deployment
2. Run deployment command
3. Capture output

1. Post-deployment checks
2. Health check endpoint responds
3. Application starts successfully
4. No immediate errors in logs
5. Smoke tests pass

1. Document deployment evidence

```markdown ## Deployment Evidence

Environment: production Timestamp: YYYY-MM-DD HH:MM:SS Version: vX.X.X

Pre-Deployment:

• Tests: ✅ Exit 0
• Build: ✅ Exit 0
• Security: ✅ No critical issues

Deployment:

• Command: kubectl apply -f deployment.yaml
• Exit Code: 0 ✅

Post-Deployment:

• Health Check: ✅ 200 OK
• Smoke Tests: ✅ All passed
• Error Rate: <0.1%

```

1. Verify rollback capability
2. Ensure previous version can be restored
3. Document rollback procedure

Evidence Storage

Where to Store Evidence

Shared Context (Primary)

{
  "quality_evidence": {
    "tests_run": true,
    "test_exit_code": 0,
    "coverage_percent": 87,
    "build_success": true,
    "build_exit_code": 0,
    "linter_errors": 0,
    "linter_warnings": 2,
    "timestamp": "2025-11-02T10:30:00Z"
  }
}

Evidence Files (Secondary)

• `.claude/quality-gates