Empirical Validation

Core Principle

"The code looks correct" is NOT validation.

Every change must be verified with empirical evidence before being marked complete.

Validation Methods by Change Type

browser_subagent

run_command

run_command

run_command

run_command

Validation Protocol

Before Marking Any Task "Done"

1. Identify Verification Criteria

   • What should be true after this change?
   • How can that be observed?

2. Execute Verification

   • Run the appropriate command or action
   • Capture the output/evidence

3. Document Evidence

   • Add to

     .agent/state/JOURNAL.md

     under the task
   • Include actual output, not just "passed"

4. Confirm Against Criteria

   • Does evidence match expected outcome?
   • If not, task is NOT complete

Examples

API Endpoint Verification

# Good: Actual test showing response
curl -X POST http://localhost:3000/api/login -d '{"email":"test@test.com"}' 
# Output: {"success":true,"token":"..."}

# Bad: Just saying "endpoint works"

UI Verification

# Good: Take screenshot with browser tool
- Navigate to /dashboard
- Capture screenshot
- Confirm: Header visible? Data loaded? Layout correct?

# Bad: "The component should render correctly"

Build Verification

# Good: Show build output
npm run build
# Output: Successfully compiled...

# Bad: "Build should work now"

Forbidden Phrases

Never use these as justification for completion:

• "This should work"
• "The code looks correct"
• "I've made similar changes before"
• "Based on my understanding"
• "It follows the pattern"

Integration

This skill integrates with:

• /verify

  — Primary workflow using this skill

• /execute

  — Must validate before marking tasks complete
• Rule 4 in

  GEMINI.md

  — Empirical Validation enforcement

Failure Handling

If verification fails:

1. Do NOT mark task complete
2. Document the failure in

   .agent/state/STATE.md

3. Create fix task if cause is known
4. Trigger Context Health Monitor if 3+ failures