self-verification-checklist

name	self-verification-checklist
description	Prevents agents from declaring work complete without running actual verification. Enforces syntax checks, test execution, and request alignment checks before any completion claim. Provides task-specific checklists and a Python verification runner.

Self-Verification Checklist Skill

Trigger Conditions

Activate this skill BEFORE any of these completion signals:

• Saying "Done", "Complete", "Finished", "That should work", "I've implemented..."
• Suggesting the user test or try the code
• Moving on to a different task after making code changes
• Responding to "is it done?" or "did you finish?"

Core Principle

Never claim completion based on intent. Only claim completion based on verification.

The agent's mental model of code is often wrong. Syntax errors, missing imports, typos, and logic bugs are invisible to reasoning but visible to execution.

---

Verification Checklists

CODE_EDIT - After Modifying Source Files

- name: syntax_check
  description: Verify file parses without syntax errors
  command: python -m py_compile {file_path}
  required: true

- name: import_check  
  description: Verify all imports resolve correctly
  command: python -c "import importlib.util; spec = importlib.util.spec_from_file_location('m', '{file_path}')"
  required: true

- name: test_execution
  description: Run project tests
  command: pytest -x --tb=short
  required: false

- name: request_alignment
  description: Agent confirms change addresses original request
  type: self-assessment
  required: true

CONFIG_CHANGE - After Modifying Config Files

- name: parse_check
  description: Verify config file parses correctly
  command: python -c "import yaml; yaml.safe_load(open('{file_path}'))"
  required: true

- name: schema_validation
  description: Validate against schema if available
  type: self-assessment
  required: false

NEW_FILE - After Creating Files

- name: file_exists
  description: Confirm file was created
  command: test -f {file_path}
  required: true

- name: not_empty
  description: Confirm file is not empty
  command: test -s {file_path}
  required: true

- name: executable_check
  description: If script, verify it can run
  command: python -m py_compile {file_path}
  required: true

---

Using the Verification Runner

The skill includes a Python verification module. Use it programmatically:

from orchestrator.verification import ChecklistRegistry, VerificationRunner

# Load checklists
registry = ChecklistRegistry("checklists.yaml")
registry.load()

# Run verification
runner = VerificationRunner(registry)
result = await runner.run("CODE_EDIT", context={"file_path": "my_module.py"})

# Check result
if result.all_passed:
    print("✅ Safe to claim completion")
else:
    print("❌ Fix issues before claiming done")
    print(result.summary)

Or via CLI:

python scripts/verify.py --task CODE_EDIT --file-path orchestrator/api.py

---

Verification Report Format

After running checks, ALWAYS report results explicitly:

✅ Good Report

Verification (CODE_EDIT):
  ✓ syntax_check: python -m py_compile api.py - PASS
  ✓ import_check: imports resolve - PASS  
  ✓ test_execution: pytest - 12 passed, 0 failed
  ✓ request_alignment: Added /api/artifacts endpoint as requested

All 4 checks passed. Ready for use.

❌ Bad Report (AVOID)

I've added the endpoint. It should work correctly.

---

Quick Reference Commands

Language	Syntax Check	Test Command
Python	python -m py_compile file.py	pytest
JavaScript	node --check file.js	npm test
TypeScript	tsc --noEmit	npm test
Go	go build ./...	go test ./...
Rust	cargo check	cargo test
YAML	python -c "import yaml; yaml.safe_load(open('f.yaml'))"	-
JSON	python -c "import json; json.load(open('f.json'))"	-

---

Anti-Patterns

1. "It should work" — Never speculate. Verify.
2. "The tests probably pass" — Run them. Report numbers.
3. "I've fixed it" — Fixed based on what verification?
4. Skipping checks for "simple" changes — Simple changes are where typos hide.

---

Exception Handling

If verification CANNOT be run:

1. Explicitly state what couldn't be verified and why
2. Suggest manual verification steps
3. Lower confidence in completion claim

Example:

Note: Could not run tests (pytest not installed). Please verify:
  1. Run `python orchestrator/api.py` to check for import errors
  2. Run `pytest` if you install it

---

Integration Flow

Before Starting Work

• Note what tests exist and current state
• Identify verification commands for this project

During Work

• Run syntax checks after each significant edit
• Don't accumulate multiple changes before verification

Before Completion

• Run full checklist for task type
• Report specific verification results
• Only then claim completion